nsaspy/starintel-auto-research

Fork 0

DESIGN_READY_FOR_OPERATOR_REVIEW: Bixby -> central ZITADEL account linking #161

New issue

Open

opened 2026-08-29 10:28:04 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-08-29 10:28:04 +00:00

Owner

Authority / state

Source research: #178
Owning implementation issue: starintel-labs/starintel-infra#39
Identity authority: starintel-labs/starintel-infra#74
Gateway/deployment: starintel-infra#34, #71
Legacy Bixby OAuth research: #144 (superseded for identity-provider ownership; retained as historical server-OAuth analysis)
Design state: DESIGN_READY_FOR_OPERATOR_REVIEW
Implementation approval: PENDING / AWAITING_OPERATOR_APPROVAL — operator only

This design is not executable by RAGE until explicit operator implementation approval is recorded.

Goal

Move Bixby signed-in user authorization to the canonical StarIntel ZITADEL issuer at auth.starintel.actor without changing guest Intelligence semantics, inventing a second identity system, or turning the Bixby gateway into an authorization server.

Final ownership

ZITADEL / `auth.starintel.actor`

Owns:

human accounts and authentication;
Bixby OAuth/OIDC client registration;
authorization endpoint;
token endpoint;
code issuance/exchange;
redirect URI enforcement;
OIDC issuer/discovery/JWKS;
stable user subject;
project roles/scopes/claims used to express StarIntel user authority.

`starintel-bixby` capsule

Owns:

authorization.bxb provider declaration;
client ID reference;
Developer Center client-secret-key name;
requested scopes;
action endpoint annotations requiring user authorization;
guest-vs-signed-in product behavior.

It owns no password store and stores no client secret in Git.

`starintel-bixby-gateway`

Owns:

resource-server validation of delegated user access tokens;
mapping validated claims/scopes into canonical StarIntel principal/capability context;
route-specific authorization checks;
separation of Bixby user authority from gateway service credentials;
bounded JWKS/discovery cache/refresh behavior;
client-safe authentication/authorization errors.

It does not mint human tokens or proxy user passwords.

Owner services

starintel-server, Quasar/Auto-Dig, and other owner services retain final operation-specific authorization and domain mutation authority. The gateway may attenuate authority; it may not expand it.

Canonical flow

Bixby user action requiring login
  -> Bixby OAuth authorization-code + PKCE flow
  -> https://auth.starintel.actor/oauth/v2/authorize
  -> StarIntel login/consent
  -> exact Samsung/Bixby registered redirect URI
  -> https://auth.starintel.actor/oauth/v2/token
  -> Bixby stores delegated user token
  -> request to starintel-bixby-gateway with user authorization
  -> gateway validates JWT/JWKS + issuer + audience + time + scopes
  -> gateway calls private owner API with distinct gateway service identity plus bounded delegated-principal context
  -> owner service authorizes operation

Exact endpoint paths should be resolved from ZITADEL discovery/config at implementation time rather than duplicated across unrelated StarIntel code, except the Bixby capsule must ultimately contain the concrete HTTPS authorize/token endpoints required by Samsung's contract.

Bixby application/client type

Use Authorization Code. Enable PKCE with S256 where compatible with the current Bixby provider flow. Bixby documentation confirms standard authorization-code + PKCE support and stores the configured client secret on Samsung servers through Developer Center Configuration & Secrets.

The exact Samsung callback URI must be registered literally in ZITADEL. No wildcard production callback.

Scope and audience model

Use stable owner-oriented capability names, not capsule-specific permissions.

Initial requested authorization:

Intelligence signed-in

OIDC: openid
StarIntel capabilities: documents:read, search:read
profile/email claims only if a concrete UX/API need exists

Operations

same StarIntel human subject;
canonical target-dispatch capability;
starintel.autodig.read;
starintel.autodig.control.

Operations must not gain operators/admins merely because the account exists or because Bixby login succeeded.

Audience must identify the intended StarIntel Bixby/gateway resource boundary. A token minted for another StarIntel app is rejected even if its issuer is valid.

Guest Intelligence invariant

Guest Intelligence remains explicitly unauthenticated/public-safe and keeps its synthetic public-read principal path.

There are two separate request modes:

guest route -> synthetic public-reader authority
signed-in route -> validated ZITADEL user authority

An invalid/expired/missing-scope token on a signed-in request is an auth failure. It must never silently downgrade to guest execution.

Token validation

Gateway validation must cover:

TLS to issuer/discovery/JWKS;
signature against issuer JWKS;
exact issuer;
expected audience;
exp and other required temporal claims;
route-required scopes/roles;
stable subject presence for user routes.

Unknown kid may trigger one bounded JWKS refresh, then fail closed. Cache lifetime/refresh must be bounded. Do not make every request depend on synchronous introspection.

If future revocation requirements demand tighter-than-expiry invalidation, add bounded introspection/revocation policy separately; do not overload the first migration slice.

Delegation into private owner APIs

Do not simply forward the Bixby bearer token everywhere as a universal infrastructure credential.

Gateway calls use the gateway's own least-privilege service identity. Where owner services need the user identity for authorization/audit, pass a typed delegated-principal envelope derived from the validated token under an authenticated internal service contract.

The envelope should carry only required fields such as:

subject
issuer
validated audience/resource
validated capability set
correlation id
original token expiry / authorization horizon

Owner services independently enforce that the gateway is authorized to assert delegated principals and that requested operations fit both service and delegated user authority.

Legacy `starintel-server` OAuth provider

Treat the old provider as a compatibility/deprecation concern, not Bixby's canonical issuer.

Before any deletion:

inventory route callers/registered clients/tests/docs;
classify reusable OAuth authorization helpers separately from public provider endpoints;
preserve any real non-Bixby consumers;
point no new Bixby registration at the old issuer;
remove/deprecate provider routes only in a later bounded issue when caller inventory proves safe.

starintel-auto-research#144 remains useful historical protocol/threat-model material but is superseded on the identity-authority decision.

Configuration / secrets

Infra owns:

ZITADEL application/client desired state;
issuer/audience configuration for the gateway;
secret delivery to runtime where required;
public auth.starintel.actor ingress through Cloudflare -> ord-edge -> mallcop -> identity origin;
TLS/health/observability.

Samsung Developer Center owns the Bixby-side stored client secret. Secret values never enter Git, issue bodies, Nix derivations, telemetry, or generated client artifacts.

Error contract

Gateway returns stable client-safe authentication outcomes such as:

AUTH_TOKEN_MISSING
AUTH_TOKEN_INVALID
AUTH_TOKEN_EXPIRED
AUTH_ISSUER_INVALID
AUTH_AUDIENCE_INVALID
AUTH_SCOPE_REQUIRED
AUTH_SUBJECT_INVALID

Do not leak token/JWKS internals or raw ZITADEL errors to Bixby.

Observability

Record safe dimensions only:

route/action class;
auth outcome class;
issuer identity as configured constant, not raw token content;
scope-check result;
latency;
correlation ID.

Never log access/refresh tokens, authorization codes, client secrets, cookies, PKCE verifier, raw ID token, or user password.

Adversarial review

Rejected:

proxy ZITADEL through starintel-server just to preserve old URLs;
gateway-issued human sessions/tokens;
one global Bixby service token shared by all users;
accepting any token from the correct issuer without audience validation;
using Bixby/Samsung account ID as canonical StarIntel subject;
forwarding user bearer token as universal backend credential;
granting Operations from login alone;
guest fallback after signed-in auth failure;
wildcard production redirect URIs;
unbounded JWKS fetch/retry or per-request dependency on identity availability;
deleting legacy server OAuth before caller inventory;
adding StarLang syntax for identity-provider plumbing.

Dependency-ordered proposed implementation slices

All remain AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL.

Contract/source migration check — change Bixby auth authority metadata/fixtures from server OAuth to central ZITADEL and add architecture invariant tests.
ZITADEL Bixby application desired state — dedicated client, redirect URI, scope/audience model; no Samsung secret value in Git.
Gateway JWT resource-server validation — issuer/discovery/JWKS/audience/time/scope checks with bounded caching and typed errors.
Delegated principal bridge — gateway service identity + typed attenuated user context into owner APIs.
Capsule authorization.bxb wiring — concrete ZITADEL authorize/token endpoints, client ID, Developer Center secret-key reference, scopes and user authorization annotations.
Legacy provider caller inventory/deprecation decision — separate bounded follow-up; no deletion unless proven safe.
End-to-end registration/device validation — manual Samsung registration values + simulator/device evidence; do not fabricate completion.

Mandatory RED-first targets

Slice 1

On untouched current starintel-bixby/main, an invariant fixture must fail because capsules/starintel-intelligence/auth.requirements.json still names starintel-server-core-oauth as signedInAuthority.

Expected desired contract: central StarIntel identity authority / auth.starintel.actor / ZITADEL.

Slice 2

A ZITADEL desired-state fixture with a callback URI different from the exact registered Samsung callback must fail validation. A secret value embedded in Nix/source must fail the secret-leak fixture.

Slice 3

Before production gateway auth changes:

wrong issuer JWT -> reject;
correct issuer/wrong audience -> reject;
expired token -> reject;
missing route scope -> reject;
unknown signing key after bounded refresh -> reject;
valid signed-in token -> produce validated principal context.

Slice 4

Fixture must prove the gateway cannot call a privileged owner operation using only its service credential when delegated user scope is absent, and cannot elevate delegated capabilities beyond the validated token.

Slice 5

Capsule contract validation must fail if OAuth endpoints are non-HTTPS, the Developer Center secret is in source, or an authenticated endpoint lacks authorization { user }.

Acceptance

Bixby signed-in flows use auth.starintel.actor / ZITADEL, not the legacy server provider;
guest Intelligence remains public-safe and separate;
exact callback/redirect URI is enforced;
Bixby secret remains Samsung-side/runtime secret material;
gateway validates issuer, signature, audience, time and scope;
same human subject can use signed-in Intelligence and Operations with different bounded capabilities;
ordinary account cannot gain operator/admin authority through Bixby;
gateway service identity and user delegated authority remain distinct;
invalid authenticated request never falls back to guest;
legacy provider is not removed until caller inventory proves safe;
no new StarLang syntax is introduced;
implementation remains blocked until explicit operator approval.

Implementation approval

PENDING / AWAITING_OPERATOR_APPROVAL

Only the operator may authorize implementation.

## Authority / state - Source research: #178 - Owning implementation issue: `starintel-labs/starintel-infra#39` - Identity authority: `starintel-labs/starintel-infra#74` - Gateway/deployment: `starintel-infra#34`, `#71` - Legacy Bixby OAuth research: #144 (superseded for identity-provider ownership; retained as historical server-OAuth analysis) - Design state: `DESIGN_READY_FOR_OPERATOR_REVIEW` - **Implementation approval: PENDING / AWAITING_OPERATOR_APPROVAL — operator only** This design is not executable by RAGE until explicit operator implementation approval is recorded. ## Goal Move Bixby signed-in user authorization to the canonical StarIntel ZITADEL issuer at `auth.starintel.actor` without changing guest Intelligence semantics, inventing a second identity system, or turning the Bixby gateway into an authorization server. ## Final ownership ### ZITADEL / `auth.starintel.actor` Owns: - human accounts and authentication; - Bixby OAuth/OIDC client registration; - authorization endpoint; - token endpoint; - code issuance/exchange; - redirect URI enforcement; - OIDC issuer/discovery/JWKS; - stable user subject; - project roles/scopes/claims used to express StarIntel user authority. ### `starintel-bixby` capsule Owns: - `authorization.bxb` provider declaration; - client ID reference; - Developer Center `client-secret-key` name; - requested scopes; - action endpoint annotations requiring user authorization; - guest-vs-signed-in product behavior. It owns no password store and stores no client secret in Git. ### `starintel-bixby-gateway` Owns: - resource-server validation of delegated user access tokens; - mapping validated claims/scopes into canonical StarIntel principal/capability context; - route-specific authorization checks; - separation of Bixby user authority from gateway service credentials; - bounded JWKS/discovery cache/refresh behavior; - client-safe authentication/authorization errors. It does not mint human tokens or proxy user passwords. ### Owner services `starintel-server`, Quasar/Auto-Dig, and other owner services retain final operation-specific authorization and domain mutation authority. The gateway may attenuate authority; it may not expand it. ## Canonical flow ```text Bixby user action requiring login -> Bixby OAuth authorization-code + PKCE flow -> https://auth.starintel.actor/oauth/v2/authorize -> StarIntel login/consent -> exact Samsung/Bixby registered redirect URI -> https://auth.starintel.actor/oauth/v2/token -> Bixby stores delegated user token -> request to starintel-bixby-gateway with user authorization -> gateway validates JWT/JWKS + issuer + audience + time + scopes -> gateway calls private owner API with distinct gateway service identity plus bounded delegated-principal context -> owner service authorizes operation ``` Exact endpoint paths should be resolved from ZITADEL discovery/config at implementation time rather than duplicated across unrelated StarIntel code, except the Bixby capsule must ultimately contain the concrete HTTPS authorize/token endpoints required by Samsung's contract. ## Bixby application/client type Register one dedicated Bixby client/application in the StarIntel ZITADEL project. Use Authorization Code. Enable PKCE with S256 where compatible with the current Bixby provider flow. Bixby documentation confirms standard authorization-code + PKCE support and stores the configured client secret on Samsung servers through Developer Center Configuration & Secrets. The exact Samsung callback URI must be registered literally in ZITADEL. No wildcard production callback. ## Scope and audience model Use stable owner-oriented capability names, not capsule-specific permissions. Initial requested authorization: ### Intelligence signed-in - OIDC: `openid` - StarIntel capabilities: `documents:read`, `search:read` - profile/email claims only if a concrete UX/API need exists ### Operations - same StarIntel human subject; - canonical target-dispatch capability; - `starintel.autodig.read`; - `starintel.autodig.control`. Operations must not gain `operators`/`admins` merely because the account exists or because Bixby login succeeded. Audience must identify the intended StarIntel Bixby/gateway resource boundary. A token minted for another StarIntel app is rejected even if its issuer is valid. ## Guest Intelligence invariant Guest Intelligence remains explicitly unauthenticated/public-safe and keeps its synthetic public-read principal path. There are two separate request modes: ```text guest route -> synthetic public-reader authority signed-in route -> validated ZITADEL user authority ``` An invalid/expired/missing-scope token on a signed-in request is an auth failure. It must never silently downgrade to guest execution. ## Token validation Gateway validation must cover: - TLS to issuer/discovery/JWKS; - signature against issuer JWKS; - exact issuer; - expected audience; - `exp` and other required temporal claims; - route-required scopes/roles; - stable subject presence for user routes. Unknown `kid` may trigger one bounded JWKS refresh, then fail closed. Cache lifetime/refresh must be bounded. Do not make every request depend on synchronous introspection. If future revocation requirements demand tighter-than-expiry invalidation, add bounded introspection/revocation policy separately; do not overload the first migration slice. ## Delegation into private owner APIs Do not simply forward the Bixby bearer token everywhere as a universal infrastructure credential. Gateway calls use the gateway's own least-privilege service identity. Where owner services need the user identity for authorization/audit, pass a typed delegated-principal envelope derived from the validated token under an authenticated internal service contract. The envelope should carry only required fields such as: ```text subject issuer validated audience/resource validated capability set correlation id original token expiry / authorization horizon ``` Owner services independently enforce that the gateway is authorized to assert delegated principals and that requested operations fit both service and delegated user authority. ## Legacy `starintel-server` OAuth provider Treat the old provider as a compatibility/deprecation concern, not Bixby's canonical issuer. Before any deletion: 1. inventory route callers/registered clients/tests/docs; 2. classify reusable OAuth authorization helpers separately from public provider endpoints; 3. preserve any real non-Bixby consumers; 4. point no new Bixby registration at the old issuer; 5. remove/deprecate provider routes only in a later bounded issue when caller inventory proves safe. `starintel-auto-research#144` remains useful historical protocol/threat-model material but is superseded on the identity-authority decision. ## Configuration / secrets Infra owns: - ZITADEL application/client desired state; - issuer/audience configuration for the gateway; - secret delivery to runtime where required; - public `auth.starintel.actor` ingress through Cloudflare -> ord-edge -> mallcop -> identity origin; - TLS/health/observability. Samsung Developer Center owns the Bixby-side stored client secret. Secret values never enter Git, issue bodies, Nix derivations, telemetry, or generated client artifacts. ## Error contract Gateway returns stable client-safe authentication outcomes such as: - `AUTH_TOKEN_MISSING` - `AUTH_TOKEN_INVALID` - `AUTH_TOKEN_EXPIRED` - `AUTH_ISSUER_INVALID` - `AUTH_AUDIENCE_INVALID` - `AUTH_SCOPE_REQUIRED` - `AUTH_SUBJECT_INVALID` Do not leak token/JWKS internals or raw ZITADEL errors to Bixby. ## Observability Record safe dimensions only: - route/action class; - auth outcome class; - issuer identity as configured constant, not raw token content; - scope-check result; - latency; - correlation ID. Never log access/refresh tokens, authorization codes, client secrets, cookies, PKCE verifier, raw ID token, or user password. ## Adversarial review Rejected: 1. proxy ZITADEL through `starintel-server` just to preserve old URLs; 2. gateway-issued human sessions/tokens; 3. one global Bixby service token shared by all users; 4. accepting any token from the correct issuer without audience validation; 5. using Bixby/Samsung account ID as canonical StarIntel subject; 6. forwarding user bearer token as universal backend credential; 7. granting Operations from login alone; 8. guest fallback after signed-in auth failure; 9. wildcard production redirect URIs; 10. unbounded JWKS fetch/retry or per-request dependency on identity availability; 11. deleting legacy server OAuth before caller inventory; 12. adding StarLang syntax for identity-provider plumbing. ## Dependency-ordered proposed implementation slices All remain **AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL**. 1. **Contract/source migration check** — change Bixby auth authority metadata/fixtures from server OAuth to central ZITADEL and add architecture invariant tests. 2. **ZITADEL Bixby application desired state** — dedicated client, redirect URI, scope/audience model; no Samsung secret value in Git. 3. **Gateway JWT resource-server validation** — issuer/discovery/JWKS/audience/time/scope checks with bounded caching and typed errors. 4. **Delegated principal bridge** — gateway service identity + typed attenuated user context into owner APIs. 5. **Capsule `authorization.bxb` wiring** — concrete ZITADEL authorize/token endpoints, client ID, Developer Center secret-key reference, scopes and user authorization annotations. 6. **Legacy provider caller inventory/deprecation decision** — separate bounded follow-up; no deletion unless proven safe. 7. **End-to-end registration/device validation** — manual Samsung registration values + simulator/device evidence; do not fabricate completion. ## Mandatory RED-first targets ### Slice 1 On untouched current `starintel-bixby/main`, an invariant fixture must fail because `capsules/starintel-intelligence/auth.requirements.json` still names `starintel-server-core-oauth` as `signedInAuthority`. Expected desired contract: central StarIntel identity authority / `auth.starintel.actor` / ZITADEL. ### Slice 2 A ZITADEL desired-state fixture with a callback URI different from the exact registered Samsung callback must fail validation. A secret value embedded in Nix/source must fail the secret-leak fixture. ### Slice 3 Before production gateway auth changes: - wrong issuer JWT -> reject; - correct issuer/wrong audience -> reject; - expired token -> reject; - missing route scope -> reject; - unknown signing key after bounded refresh -> reject; - valid signed-in token -> produce validated principal context. ### Slice 4 Fixture must prove the gateway cannot call a privileged owner operation using only its service credential when delegated user scope is absent, and cannot elevate delegated capabilities beyond the validated token. ### Slice 5 Capsule contract validation must fail if OAuth endpoints are non-HTTPS, the Developer Center secret is in source, or an authenticated endpoint lacks `authorization { user }`. ## Acceptance - Bixby signed-in flows use `auth.starintel.actor` / ZITADEL, not the legacy server provider; - guest Intelligence remains public-safe and separate; - exact callback/redirect URI is enforced; - Bixby secret remains Samsung-side/runtime secret material; - gateway validates issuer, signature, audience, time and scope; - same human subject can use signed-in Intelligence and Operations with different bounded capabilities; - ordinary account cannot gain operator/admin authority through Bixby; - gateway service identity and user delegated authority remain distinct; - invalid authenticated request never falls back to guest; - legacy provider is not removed until caller inventory proves safe; - no new StarLang syntax is introduced; - implementation remains blocked until explicit operator approval. ## Implementation approval `PENDING / AWAITING_OPERATOR_APPROVAL` Only the operator may authorize implementation.

nsaspy referenced this issue

2026-08-29 10:28:07 +00:00

StarLang research: OSINT domain-server orchestration gaps #175

nsaspy referenced this issue

2026-08-29 10:29:16 +00:00

feat(research): migrate approval queue end-to-end #155