nsaspy/starintel-auto-research

Fork 0

P0 ARDR research: migrate Bixby account linking from server OAuth authority to central ZITADEL #162

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

StarIntel problem solved

Reconcile the open P0 identity conflict in starintel-labs/starintel-infra#39.

Older Bixby research/design (#144) treated the standalone starintel-server OAuth authorization-code provider as the public identity authority. Current StarIntel architecture makes self-hosted ZITADEL at auth.starintel.actor the canonical identity authority (starintel-infra#74). The Bixby capsule/gateway contract must migrate without duplicating identity systems, losing scope semantics, or breaking guest Intelligence.

Owning implementation issue: starintel-labs/starintel-infra#39.
Related deployment/gateway issues: starintel-infra#34, #71, #74.
Legacy research: starintel-auto-research#144.

ARDR state

READY_FOR_DESIGN

Implementation approval remains operator-only.

Current source evidence

Current lost-rob0t/starintel-bixby/main still records signed-in Intelligence authority as starintel-server-core-oauth and marks the server provider implemented, while registration remains incomplete. Operations already models OAuth authorization-code user authority and delegates execution through the infra-owned Bixby gateway.

This means the migration can occur before Samsung registration is complete and without preserving a deployed Bixby dependency on the legacy provider.

Current upstream evidence

Bixby

Current Bixby Developer Center documentation confirms:

authorization.bxb supports standard OAuth 2.0 authorization-code flows;
PKCE is supported, with S256 / SHA256 challenge methods;
authorize-endpoint, token-endpoint, client-id, client-secret-key, and optional scope are native capsule configuration;
the client secret is stored in Samsung Developer Center Configuration & Secrets, not in capsule source;
OAuth endpoints must use HTTPS;
Bixby stores/manages the resulting user access key/token for authorized endpoints.

Therefore Bixby does not require a StarIntel-specific authorization server implementation. It can target standards-shaped ZITADEL OAuth/OIDC endpoints directly.

ZITADEL

Current ZITADEL documentation confirms:

Authorization Code is supported directly;
PKCE is recommended and supported;
redirect URIs are registered and strictly validated;
discovery metadata and JWKS are exposed from the issuer;
access/ID tokens carry standard issuer/audience/expiry semantics suitable for independent resource-server validation;
per-application clients and scopes are supported.

Research decision

The canonical Bixby user authorization path is:

Bixby capsule
  -> auth.starintel.actor / ZITADEL authorize
  -> StarIntel user authentication/consent
  -> Samsung/Bixby registered callback
  -> ZITADEL token endpoint
  -> Bixby-managed delegated user token
  -> starintel-bixby-gateway
  -> canonical private StarIntel owner APIs

The legacy starintel-server OAuth provider is not the long-term Bixby identity authority.

Identity and token boundary

ZITADEL owns human account authentication and authorization-code issuance.
Bixby is one registered OAuth/OIDC client.
Samsung/Bixby stores the Bixby client secret in Developer Center secrets.
The Bixby gateway validates delegated tokens independently before accepting authenticated routes.
Gateway service identity remains distinct from the user's token.
Owner services remain authoritative for operation-specific authorization.
Bixby user identifiers are not StarIntel principals.
Guest Intelligence remains a separate anonymous/public-reader path and never becomes a fallback for a failed authenticated/private request.

Scope mapping

Preserve existing StarIntel capability meaning instead of inventing Bixby-only permissions.

Initial mapping target:

Intelligence signed-in read: documents:read, search:read;
Operations target mutation: canonical target-dispatch scope from owning server contract;
Auto-Dig: starintel.autodig.read, starintel.autodig.control;
OIDC identity scopes: openid plus only profile claims actually needed by the gateway/product.

The exact ZITADEL project roles/audience claims must map to owner-service scopes; a successful login alone grants no operator/admin capability.

Legacy server OAuth migration classification

Do not delete the existing starintel-server OAuth core/provider merely because Bixby moves.

Before removal/deprecation:

enumerate current clients/callers of the legacy authorize/token surface;
distinguish reusable authorization/resource-server helpers from the public identity-provider role;
preserve non-Bixby compatibility where an actual caller exists;
otherwise mark the provider surface deprecated after Bixby migration, with no new clients pointed at it.

The server may continue to validate/authorize StarIntel tokens and own service policy without owning user login.

Required gateway validation

The gateway must reject:

wrong issuer;
wrong audience;
expired/not-yet-valid token;
invalid signature / unknown key after bounded JWKS refresh;
missing operation scope;
ordinary user token presented for operator-only operation;
token intended for a different StarIntel client/resource;
authenticated-route failure that attempts to fall back to guest authority.

Validation must be based on issuer discovery/JWKS and stable claims, not a network call to ZITADEL on every request unless a later revocation policy specifically requires introspection.

Registration/manual boundary

Samsung Developer Center remains an operator/manual boundary for values Samsung requires, including:

capsule registration/submission state;
exact Samsung callback/redirect URI;
Bixby OAuth client ID;
Developer Center secret-key entry containing the corresponding client secret.

Infra may generate/document the expected values but must not fabricate successful Samsung registration.

StarLang classification

No new StarLang syntax is justified.

Identity-provider deployment/configuration belongs to StarIntel infra; gateway token validation belongs to the gateway/runtime adapter; owner-service authorization remains in canonical service policy. StarLang-defined actors/domain servers consume already-authorized principal/capability context and cannot mint or expand user authority.

Adversarial findings

Rejected:

Keep both public identity providers active for Bixby — creates competing account/token authority and drift.
Put ZITADEL behind a custom starintel-server OAuth facade — preserves unnecessary duplicate protocol authority and complicates issuer/audience semantics.
Use the gateway as OAuth token broker — conflates translation/service identity with human identity authority.
Trust Bixby merely because Samsung performed OAuth — the gateway still validates signature, issuer, audience, expiry and scope.
Reuse the user bearer token as gateway infrastructure credentials — confused-deputy boundary violation.
Treat ordinary account creation as Operations authorization — account existence is not privileged capability.
Delete legacy server OAuth blindly — unknown non-Bixby clients could break.
Fallback to guest on invalid signed-in requests — can silently downgrade private intent into the wrong authority path.
Depend on token introspection for every request in v1 — unnecessary availability coupling when JWT/JWKS validation is sufficient for ordinary access-token validation.

Mandatory RED-first targets for eventual implementation

No production mutation before RED evidence.

Capsule contract fixture currently naming starintel-server-core-oauth must fail the desired architecture check requiring auth.starintel.actor / central ZITADEL authority.
Gateway auth fixture with validly shaped but wrong-issuer JWT must be rejected.
Correct issuer but wrong audience must be rejected.
Missing targets:dispatch or Auto-Dig control scope must reject corresponding Operations action.
Invalid authenticated Intelligence token must not fall back to synthetic guest authority.
Legacy-server OAuth client inventory test/check must identify callers before any deprecation/removal step.

Decision

Evidence is sufficient to proceed directly to design. No unresolved architecture question requires human research validation.

Implementation approval: PENDING / AWAITING_OPERATOR_APPROVAL.

## StarIntel problem solved Reconcile the open P0 identity conflict in `starintel-labs/starintel-infra#39`. Older Bixby research/design (`#144`) treated the standalone `starintel-server` OAuth authorization-code provider as the public identity authority. Current StarIntel architecture makes self-hosted ZITADEL at `auth.starintel.actor` the canonical identity authority (`starintel-infra#74`). The Bixby capsule/gateway contract must migrate without duplicating identity systems, losing scope semantics, or breaking guest Intelligence. Owning implementation issue: `starintel-labs/starintel-infra#39`. Related deployment/gateway issues: `starintel-infra#34`, `#71`, `#74`. Legacy research: `starintel-auto-research#144`. ## ARDR state `READY_FOR_DESIGN` Implementation approval remains operator-only. ## Current source evidence Current `lost-rob0t/starintel-bixby/main` still records signed-in Intelligence authority as `starintel-server-core-oauth` and marks the server provider implemented, while registration remains incomplete. Operations already models OAuth authorization-code user authority and delegates execution through the infra-owned Bixby gateway. This means the migration can occur before Samsung registration is complete and without preserving a deployed Bixby dependency on the legacy provider. ## Current upstream evidence ### Bixby Current Bixby Developer Center documentation confirms: - `authorization.bxb` supports standard OAuth 2.0 authorization-code flows; - PKCE is supported, with `S256` / `SHA256` challenge methods; - `authorize-endpoint`, `token-endpoint`, `client-id`, `client-secret-key`, and optional `scope` are native capsule configuration; - the client secret is stored in Samsung Developer Center Configuration & Secrets, not in capsule source; - OAuth endpoints must use HTTPS; - Bixby stores/manages the resulting user access key/token for authorized endpoints. Therefore Bixby does not require a StarIntel-specific authorization server implementation. It can target standards-shaped ZITADEL OAuth/OIDC endpoints directly. ### ZITADEL Current ZITADEL documentation confirms: - Authorization Code is supported directly; - PKCE is recommended and supported; - redirect URIs are registered and strictly validated; - discovery metadata and JWKS are exposed from the issuer; - access/ID tokens carry standard issuer/audience/expiry semantics suitable for independent resource-server validation; - per-application clients and scopes are supported. ## Research decision The canonical Bixby user authorization path is: ```text Bixby capsule -> auth.starintel.actor / ZITADEL authorize -> StarIntel user authentication/consent -> Samsung/Bixby registered callback -> ZITADEL token endpoint -> Bixby-managed delegated user token -> starintel-bixby-gateway -> canonical private StarIntel owner APIs ``` The legacy `starintel-server` OAuth provider is not the long-term Bixby identity authority. ## Identity and token boundary 1. ZITADEL owns human account authentication and authorization-code issuance. 2. Bixby is one registered OAuth/OIDC client. 3. Samsung/Bixby stores the Bixby client secret in Developer Center secrets. 4. The Bixby gateway validates delegated tokens independently before accepting authenticated routes. 5. Gateway service identity remains distinct from the user's token. 6. Owner services remain authoritative for operation-specific authorization. 7. Bixby user identifiers are not StarIntel principals. 8. Guest Intelligence remains a separate anonymous/public-reader path and never becomes a fallback for a failed authenticated/private request. ## Scope mapping Preserve existing StarIntel capability meaning instead of inventing Bixby-only permissions. Initial mapping target: - Intelligence signed-in read: `documents:read`, `search:read`; - Operations target mutation: canonical target-dispatch scope from owning server contract; - Auto-Dig: `starintel.autodig.read`, `starintel.autodig.control`; - OIDC identity scopes: `openid` plus only profile claims actually needed by the gateway/product. The exact ZITADEL project roles/audience claims must map to owner-service scopes; a successful login alone grants no operator/admin capability. ## Legacy server OAuth migration classification Do not delete the existing `starintel-server` OAuth core/provider merely because Bixby moves. Before removal/deprecation: - enumerate current clients/callers of the legacy authorize/token surface; - distinguish reusable authorization/resource-server helpers from the public identity-provider role; - preserve non-Bixby compatibility where an actual caller exists; - otherwise mark the provider surface deprecated after Bixby migration, with no new clients pointed at it. The server may continue to validate/authorize StarIntel tokens and own service policy without owning user login. ## Required gateway validation The gateway must reject: - wrong issuer; - wrong audience; - expired/not-yet-valid token; - invalid signature / unknown key after bounded JWKS refresh; - missing operation scope; - ordinary user token presented for operator-only operation; - token intended for a different StarIntel client/resource; - authenticated-route failure that attempts to fall back to guest authority. Validation must be based on issuer discovery/JWKS and stable claims, not a network call to ZITADEL on every request unless a later revocation policy specifically requires introspection. ## Registration/manual boundary Samsung Developer Center remains an operator/manual boundary for values Samsung requires, including: - capsule registration/submission state; - exact Samsung callback/redirect URI; - Bixby OAuth client ID; - Developer Center secret-key entry containing the corresponding client secret. Infra may generate/document the expected values but must not fabricate successful Samsung registration. ## StarLang classification No new StarLang syntax is justified. Identity-provider deployment/configuration belongs to StarIntel infra; gateway token validation belongs to the gateway/runtime adapter; owner-service authorization remains in canonical service policy. StarLang-defined actors/domain servers consume already-authorized principal/capability context and cannot mint or expand user authority. ## Adversarial findings Rejected: 1. **Keep both public identity providers active for Bixby** — creates competing account/token authority and drift. 2. **Put ZITADEL behind a custom starintel-server OAuth facade** — preserves unnecessary duplicate protocol authority and complicates issuer/audience semantics. 3. **Use the gateway as OAuth token broker** — conflates translation/service identity with human identity authority. 4. **Trust Bixby merely because Samsung performed OAuth** — the gateway still validates signature, issuer, audience, expiry and scope. 5. **Reuse the user bearer token as gateway infrastructure credentials** — confused-deputy boundary violation. 6. **Treat ordinary account creation as Operations authorization** — account existence is not privileged capability. 7. **Delete legacy server OAuth blindly** — unknown non-Bixby clients could break. 8. **Fallback to guest on invalid signed-in requests** — can silently downgrade private intent into the wrong authority path. 9. **Depend on token introspection for every request in v1** — unnecessary availability coupling when JWT/JWKS validation is sufficient for ordinary access-token validation. ## Mandatory RED-first targets for eventual implementation No production mutation before RED evidence. 1. Capsule contract fixture currently naming `starintel-server-core-oauth` must fail the desired architecture check requiring `auth.starintel.actor` / central ZITADEL authority. 2. Gateway auth fixture with validly shaped but wrong-issuer JWT must be rejected. 3. Correct issuer but wrong audience must be rejected. 4. Missing `targets:dispatch` or Auto-Dig control scope must reject corresponding Operations action. 5. Invalid authenticated Intelligence token must not fall back to synthetic guest authority. 6. Legacy-server OAuth client inventory test/check must identify callers before any deprecation/removal step. ## Decision Evidence is sufficient to proceed directly to design. No unresolved architecture question requires human research validation. Implementation approval: `PENDING / AWAITING_OPERATOR_APPROVAL`.

nsaspy referenced this issue

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

StarLang research: OSINT domain-server orchestration gaps #175