Status: implemented and wired to the KAS relay. The auth subsystem lives under
src/kiro_crew/auth/with unit tests. Its runtime consumer issrc/kiro_crew/acp/kas_host_auth.py: when the vault holds an identity, the KAS backend spawns the relay inacp --agent-engine v3mode WITHOUT--auth-method cli, so the engine's_kiro/auth/getAccessTokenrequest reaches Kiro Crew, andAcpRuntimeanswers it fromKasAuthProvider.get_access_token_callback(). That spawn enters throughkiro-cli-chatwhen one sits beside the resolvedkiro-cli(kiro_cli.chat_sibling, consulted byacp/harness/kas.pyon the Crew-owned branch only, never for an explicitKIROCREW_KIRO_BIN, never on Windows whose onekiro-cli.exeis the chat-cli crate itself): the POSIXkiro-cliis the q_cli launcher, and it checks its OWN sign-in before exec'ingkiro-cli-chatforacpregardless of--auth-method, so through it a Crew-owned spawn on a host where kiro-cli is signed out -- the host this mode exists for -- exitsYou are not logged inbefore the engine ever asks Crew (measured on kiro-cli 2.25.0;kiro-cli-chat acp --agent-engine v3starts KAS in--auth=acp-callbackand the turn completes). With no identity stored the spawn keeps--auth-method clithrough the launcher and kiro-cli owns login exactly as before, an API-key sign-in included: that cli-owned relay is handedKIRO_API_KEYlike the kiro backend, while a Crew-owned relay has it stripped because the engine prefers an environment key over the callback (KasHarness.apply_spawn_env,cli_owned_auth). On the relay route kiro-cli remains the ACP service either way. On the bundle route (agent.kas_bundle, acp-client.md § KAS bundle route) Crew spawns its own installed engine and is the auth owner unconditionally: the callback always reaches Crew, and there is no--auth-method clito fall back to.Choosing KAS means Kiro Crew's own sign-in (decision 2026-10-30). Where the relay cannot run -- no kiro-cli, or a kiro-cli whose own sign-in is proven absent and through which the vault cannot reach the engine (no
kiro-cli-chatentry) -- a KAS spawn takes the bundle route automatically (acp/kas_route.py), and the gateway installs the pinned engine when it is missing. So the vault sign-in always takes effect on the next spawn, and every KAS prompt points at the Kiro sign-in card and never atkiro-cli login: the declaration'ssign_in_remedyandsigned_out_messagename that card alone, led by the route of the last spawn once one ran (host_auth._with_kas_route);kirocrew doctor'skas auth:row names the route ("KAS through kiro-cli's relay") and prints the same remedy when kiro-cli's own store is what answers. A stored Kiro CLI pick (agent.acp_backend == "kiro") is not moved: it keeps kiro-cli's sign-in.
In the kiro-cli runtime, Kiro Crew holds no Kiro credentials of its own: every ACP
backend delegates auth to the kiro-cli process it spawns. In KAS mode kiro-cli
stays the ACP relay, but it does not own the credential: the engine asks the host
for a token with _kiro/auth/getAccessToken, and Kiro Crew answers it from
acp/kas_host_auth.py. So Kiro Crew performs the entire Kiro OIDC lifecycle itself:
interactive login, token refresh, secure storage, and identity classification.
In scope: obtaining and maintaining a valid Kiro access token for the four identity types Kiro supports, across the three Kiro Crew install shapes, and handing it to KAS.
Out of scope: the KAS runtime itself, model routing, governance evaluation (KAS owns
that, keyed off the provider field this module supplies).
Confirmed against @kiro/agent source (packages/kiro-agent/src/server/). KAS
consumes a token through one of two injection points; both take the same logical
contract:
-
Library injection (in-process KAS; unbuilt design). Kiro Crew does not run KAS in-process today, so this point is not wired; it records the contract a future in-process host would meet.
KiroAgentOptions.authProvideris a required constructor field of typeIAuthProvider(src/index.tsexportsIAuthProvider). Interface:interface IAuthProvider { getToken(): Promise<string>; // may trigger refresh getProfileArn(): Promise<string | undefined>; isAuthenticated(): boolean; readToken(): { authMethod?: string; provider?: string } | undefined; // no refresh region?: string; }
Built-in providers also implement
RequestCredentialResolver.resolveRequestCredential(): Promise<{accessToken, profileArn, provider}>(an atomic snapshot used by the BFF header middlewareaddKiroAuthHeaders). Our implementation SHOULD implement it too, so the full request path is exercised. -
acp-callback (the shipped path). KAS, behind the kiro-cli relay, calls back
_kiro/auth/getAccessToken(empty request body). Response shape (packages/acp-type-covenant/capabilities/auth/get-access-token.ts):{ accessToken: string; // required expiresAt: string; // required ISO-8601, MUST be > now + 3min profileArn?: string; // SHOULD; missing -> region falls back us-east-1 + warn authMethod?: string; // 'external_idp' -> TokenType header; else omit provider?: string; } // governance classification (see below)
Required fields either way: accessToken + expiresAt (delivered ≥ now+3min).
provider drives KAS governance (governance-service.ts) and the X-Kiro-Idp
header. Getting it wrong misroutes governance and can fail-closed. Mapping:
| Kiro Crew login | provider value |
governance-enterprise? | notes |
|---|---|---|---|
| AWS Builder ID | BuilderId |
no | MUST be set; empty → misclassified |
| Social — Google | Google |
no | |
| Social — GitHub | Github |
no | |
| IAM Identity Center | Enterprise |
yes | profileArn mandatory (region routing) |
| External IdP federation | ExternalIdp |
yes | authMethod: 'external_idp', needs tokenEndpoint for refresh |
| Amazon internal | Internal |
no (but admin-billing) |
profileArn: mandatory for enterprise/IdC (feeds X-Kiro-Profile-Arn, and its 4th ARN
segment is the region source). Optional for Builder ID / social (falls back to
us-east-1). Social device-flow uses a shared default profile ARN.
The wire contract below is reverse-engineered from kiro-cli source
(crates/chat-cli/src/auth/{portal.rs, social.rs, builder_id.rs, external_idp.rs, oauth_callback.rs, pkce.rs, consts.rs}) and validated end-to-end for social device
flow (a real Google token was obtained with a stdlib-only client, no kiro-cli — see
PoC note below).
The single most important design rule: detect the install shape and pick the
transport that can receive the result. kiro-cli already does this with is_remote().
| Install shape | Browser vs gateway | Transport | Rationale |
|---|---|---|---|
| Desktop app / native local | same machine | loopback callback | browser hits localhost:<port>, gateway is listening there |
| Local container (Docker) | browser on host, gateway in container | loopback callback, requires -p 127.0.0.1:<port>:<port> mapping |
callback must be port-mapped into the container |
| Remote host (VPS / cloud / remote desk) | browser on laptop, gateway remote | device code | remote localhost ≠ laptop localhost; device flow needs no callback port |
Fallback rule: if the loopback bind fails or the shape is remote/headless, use device code. Device code works everywhere, so it is the safe default when detection is uncertain.
A poll is the longest-lived request in a login: one every few seconds for as long as the user takes to approve in their browser. The dashboard treats the poll route's 502 as terminal and offers only "start over", so a poll must report a failed login only when the login has actually failed.
The transport budget below is shared by both device flavors; the two rows marked by-flavor are not.
| What the poll sees | Answer | Why |
|---|---|---|
authorization_pending / slow_down |
pending |
the user has not finished yet |
| a body that cannot be read at all (unreadable, undecodable, mislabelled charset) | pending, no budget charged |
the issuer answered; the flow's own expiry bounds retries |
no answer at all (dropped connection, DNS blip, connect timeout), up to MAX_POLL_TRANSPORT_FAILURES in a row |
pending |
says nothing about the login — the device authorization is still valid at the issuer |
| no answer at all, past that budget | raise → coded 502 | a sustained outage is real and is reported as such |
expired_token |
expired |
terminal |
| anything else | error |
terminal |
Two rows differ by flavor, so read them per poll rather than as one rule:
| What the poll sees | Social device poll | SSO-OIDC token poll |
|---|---|---|
HTTP 5xx whose body decodes but carries no recognized code (e.g. {"__type":"InternalServerException"}) |
pending — any non-200 is a hiccup |
error, terminal — an unrecognized error is a rejection (BuilderIdAuthError) |
| a 200 whose body is valid JSON but not an object | pending |
error, terminal (CreateToken returned a non-object body) |
The budget is per pending login and counts consecutive failures that never reached
the issuer. A poll that got an answer clears it — including one whose answer could not
be read, because that answer still proves the service is up — so only a sustained
outage crosses it, and the count disappears with the login entry. The IdC profile-ARN
resolution that follows an approved token carries no budget — its device code is
already redeemed, so a later poll cannot re-obtain the token and pending would only
loop until expiry.
Every request on the shared auth session is bounded by an explicit ClientTimeout
(total=30s, connect=10s). aiohttp's own default is five minutes, which on a
black-holed route holds a poll far past its own cadence.
Brokered entirely by Kiro's servers — there is no independent OAuth client we can
stand up, but there is also no per-app secret to obtain. The only client
identifier sent is the literal User-Agent "Kiro-CLI". We replicate the flow by
driving Kiro's own portal/service exactly as the CLI does. This works only as long as
Kiro's server keeps accepting the kirocli portal contract and the allowlisted ports.
Endpoints (host: https://prod.us-east-1.auth.desktop.kiro.dev, portal:
https://app.kiro.dev; both overridable — KIRO_AUTH_SERVICE_URL for the service,
KIRO_AUTH_PORTAL_URL for the portal):
- Loopback: open
GET {portal}/signin?state=…&code_challenge=…&code_challenge_method=S256&redirect_uri=http://localhost:<port>&redirect_from=kirocli; listen on a Cognito-allowlisted port (see below); portal redirects to/oauth/callback?login_option=<google|github>&code=…&state=…; thenPOST {host}/oauth/tokenwith{code, code_verifier, redirect_uri}whereredirect_uriMUST equalhttp://localhost:<port>/oauth/callback?login_option=<p>(path + login_option query, exactly as rebuilt in portal.rs). - Device code:
POST {host}/oauth/device/authorization{clientId:"Kiro-CLI", loginProvider:"Google"|"Github"}→{deviceCode, userCode, verificationUri, verificationUriComplete, expiresInMilliseconds, intervalInMilliseconds}; user approvesverificationUriComplete; pollPOST {host}/oauth/device/poll{deviceCode, clientId:"Kiro-CLI"}untilstatus:"authorized".
Response (camelCase): {accessToken, refreshToken, expiresIn, profileArn}. A non-empty
profileArn is mandatory. Device poll may omit expiresIn — default to 3600s (as
kiro-cli does) or parse the JWT exp.
Allowlisted callback ports (do not change without auth-service coordination):
[3128, 4649, 6588, 8008, 9091, 49153, 50153, 51153, 52153, 53153].
Standard AWS SSO-OIDC. No Kiro-controlled gate. Runtime dynamic client
registration (RegisterClient, client_type=public, client_name="Kiro Crew") →
returns client_id + client_secret; PKCE authorization-code on an arbitrary loopback
port (or device code via StartDeviceAuthorization); CreateToken. Endpoints:
https://oidc.<region>.amazonaws.com (Builder ID region us-east-1). Scopes:
codewhisperer:completions|analysis|conversations. Start URLs: Builder ID
https://view.awsapps.com/start; internal https://amzn.awsapps.com/start.
An Identity Center start URL is canonicalized before StartDeviceAuthorization
(auth/service._canonical_start_url, through the cloud login target's
normalize_start_url, so the vault and a cloud target record the same string): a
missing https:// and a missing /start are added and a #/... fragment is dropped,
because SSO-OIDC answers Invalid start url provided to <org>.awsapps.com/start
and to https://<org>.awsapps.com. A URL it cannot canonicalize (http://, a query,
a port, shell characters) is refused with invalid_start_url before AWS is called.
A 400 invalid_request from StartDeviceAuthorization for a company start URL is
StartUrlRejectedError, also invalid_start_url (HTTP 400, not the 502 of an
auth-service failure): its message says to use the access portal URL when AWS names
the start URL, and to check the Region field otherwise, since a portal looked up in
the wrong region answers a bare Invalid request.
Portal returns IdP metadata (issuer_url, client_id, scopes, login_hint,
audience); run standard authorization-code against the customer's own IdP; refresh at
the token's own tokenEndpoint with grant_type=refresh_token. Ensure
offline_access scope for refresh.
Each identity refreshes on its own endpoint; the module owns the refresh and the cross-process lock (KAS just re-reads / re-callbacks):
| Identity | Refresh endpoint | Protocol |
|---|---|---|
| Social + Builder ID (social path) | POST {host}/refreshToken |
JSON {refreshToken} → {accessToken, refreshToken?, expiresIn, profileArn?} |
| IAM Identity Center | AWS SSO-OIDC CreateToken |
needs stored {clientId, clientSecret} from RegisterClient |
| External IdP | token's tokenEndpoint |
OAuth grant_type=refresh_token |
Refresh window: KAS enters its refresh buffer at now + 3min. The module MUST ensure
a token satisfying expiresAt ≥ now+3min whenever queried. Use a single-flight
cross-process lock (mirror kiro-cli's refresh_coordinator) so concurrent sessions
don't stampede the refresh endpoint; re-read the store inside the lock and skip the
HTTP call if a peer already refreshed.
Two callers renew a stored identity, both through auth/refresh.ensure_fresh, so
the lock above orders them: the engine's _kiro/auth/getAccessToken callback
(KasAuthProvider.current), and a gateway tick
(dashboard/sign_in_refresher.run_sign_in_refresher, started beside the
stale-asset watchdog) that sleeps until the highest-priority stored identity
enters the margin and renews it then, so the stored expiry the sign-in card and
kirocrew doctor read does not freeze while no agent turn runs. The
tick never renews a token outside the margin, does not retry while the
refresh-rejected marker stands (a new sign-in clears it), backs off from 30s to
5min on a transient failure, and does not import kiro_crew.auth until the vault
file exists. It renews while the gateway is idle too, so a refused renewal
surfaces without waiting for a chat turn. Each renewal request is capped at
8s, and gateway shutdown waits up to 9s (alongside, and inside, the graceful
shutdown budget) for an in-flight renewal to finish
(drain_sign_in_refresher), so a rotated refresh token is persisted rather
than consumed at the issuer and lost to the hard exit.
Context: kiro-cli does not encrypt its tokens — they live plaintext in a SQLite
auth_kv table protected only by 0600 file perms. Kiro Crew deliberately does
better, because it faces a threat kiro-cli does not: its own AI agent reads files on
the same machine.
KAS tokens live in a dedicated SecretVault instance rooted at
<data_home>/kas (store kas/.vault/secrets.enc, key kas/.vault/.vault_key):
per-entry AES-256-GCM with per-entry AAD (entry transplant fails decryption),
atomic replace + fsync, cross-process flock, owner-only modes / Windows ACLs — all
provided by kiro_crew.secrets.SecretVault, not reimplemented. Entry name = the
identity kind (social / builder_id / identity_center / external_idp), value
= the token JSON.
This is deliberately NOT the user-facing secrets vault (config_dir()): login
credentials are auto-refreshed session state managed by the login/logout UI, not
user-provided integration secrets. A separate store path and key keeps them out of
the /api/secrets panel and keeps delete semantics distinct (logout vs
disconnect-integration).
Defense in depth: the whole kas directory (vault included) is a keystone leaf in
security._CREW_SECRET_LEAVES, so the agent can neither read nor write its own
credential store — the denylist blocks the tools, and encryption at rest means a
ciphertext-only leak (backup, sync, accidental read) discloses nothing without the
key file. The directory is also an OS-level sandbox mask, and because the store
creates it on the first sign-in, kas is in
sandbox._CREW_PRECREATE_HIDDEN_DIR_LEAVES: it exists (empty, 0700) before every
Linux namespace spawn, so a sandbox started before that sign-in still has it masked.
Do not weaken either layer. The threat model is honest about its limits:
a same-UID attacker who can read the key file can decrypt — the vault defends
against agent reads and ciphertext-only leaks, not same-UID malware (same position
as sops/age key files and Ansible vault-password files).
Error split at the store API: an unknown identity kind raises ValueError (HTTP
400 at the API layer); a vault read/write failure raises TokenStoreError (coded
HTTP 500) — a logout that could not remove the credential never reports success.
Priority when multiple credentials exist (store._PRIORITY, mirroring kiro-cli
auth/mod.rs): External IdP > Builder ID > Identity Center > Social, then
KIRO_API_KEY env as final fallback.
New subsystem src/kiro_crew/auth/ (implemented):
auth/
__init__.py
provider.py # KasAuthProvider: implements the IAuthProvider contract
bridge.py # KAS seam: acp-callback handler + IAuthProvider-shaped mapping
refresh.py # per-identity refresh + cross-process single-flight lock
store.py # SecretVault adapter (kas/.vault) + identity priority resolver
service.py # KasLoginService: begin/poll/cancel/logout state machine for the API
shape.py # install-shape detection -> transport selection
login/
endpoints.py # endpoint constants (mirror consts.rs; env-overridable)
portal.py # loopback callback flow (PKCE + allowlisted-port listener)
device.py # social device-code flow (no callback)
builder_id.py # AWS SSO-OIDC RegisterClient + device-code
external_idp.py # customer IdP authorization-code
control_plane.py # ListAvailableProfiles: resolves the profile ARN for IdC sign-in
Wiring: the KAS bridge answers _kiro/auth/getAccessToken (acp-callback) from
KasAuthProvider. Handing KasAuthProvider to KiroAgentOptions.authProvider for an
in-process KAS is unbuilt design. Refresh tokens never leave Kiro Crew; KAS only ever sees an
access token.
- Token store paths join
security._SENSITIVE_HOME_DIRS; agent cannot read/write them. - Refresh tokens and access tokens never appear in chat surfaces or logs (extend the existing credential-redaction floor).
- The child process running any browser-open MUST bind the callback listener to
127.0.0.1only. - The loopback sign-in listener (
auth/login/portal.py:bind_allowed_port) claims its port per platform:SO_REUSEADDRon POSIX (a rebind throughTIME_WAIT; a live listener still refuses it) andSO_EXCLUSIVEADDRUSEon Windows, where two listeners that both setSO_REUSEADDRshare one address and the browser's callback can reach either. A held port then fails the bind and the loop takes the next allowlisted port.test/test_reuseaddr_platform_branch.pyfails any productionSO_REUSEADDRset outside a platform branch. KIRO_API_KEYremains a supported headless path (matches KASEnvAuthProvider). Its ApiKey identity has no SSO/OIDC bearer, so theGetUsageLimitsAPI is skipped for it (that call can only answer 403); credit usage comes from the/usagescrape instead, which kiro-cli answers locally for the signed-in key.
The dashboard card is one driver of KasLoginService; kirocrew kas login | whoami | logout | route (cli_kas_login.py) is the other, for a host with no browser and no
dashboard session. It exists because on the bundle route the vault is the engine's
ONLY credential and kiro-cli is not installed, so kiro-cli login/whoami/logout have
nothing to act on there. The verbs deliberately speak kiro-cli's vocabulary:
| Verb | Does | Output / exit |
|---|---|---|
kas login [--provider builder_id|idc|google|github] [--start-url] [--region] |
device-code sign-in (the one transport that needs no callback to reach the host), polls until approved, saves to the vault | prints Open <verification URL> and code: XXXX-XXXX, exits 0 once stored; on a vault that already holds a usable identity prints already signed in and exits 0 (switching is logout then login) |
kas whoami [--format json] |
who the vault is signed in as: KasToken.is_usable (the predicate the spawn reads) AND no refresh-rejected marker on the slot, so a sign-in doctor and the card call "expired -- sign in again" reads as signed out here too and kas login replaces it |
exit 0 + the kiro-cli whoami --format json document (auth/whoami.whoami_document: accountType, and startUrl when recorded -- nothing else, never a token or e-mail); exit 1 when signed out |
kas logout |
removes every stored identity (KasLoginService.logout) and bumps the store's sign-out generation (below) |
a running gateway retires its agent processes on the next turn: the vault is in its identity fingerprint and the pre-turn identity-change check runs the same sweep the dashboard's sign-out runs; a dashboard login pending at that moment is refused when its code is approved |
kas route |
which program owns the Kiro sign-in on this host | kas-bundle when agent.acp_backend == "kas" AND Crew owns the credential: the vault holds an identity (every KAS spawn then draws on it, so a sign-in never flips the answer back to kiro-cli), or the bundle route (agent.kas_bundle on, or chosen automatically because kiro-cli's relay cannot run here, acp/kas_route.py); kiro-cli otherwise; a config that cannot be read -- a load that raised, OR one the loader returned as defaults with _base_unreadable / _overlay_unreadable set (auth/whoami.load_sign_in_owner_config) -- is a plain-language error naming the path and the fault, exit 1: the owner is then UNKNOWN, never kiro-cli, so a remote script neither runs a kiro-cli branch on a bundle-route box nor signs the wrong store out. The predicate itself is auth/whoami.agent_owns_sign_in(agent), the one in-process spelling |
accountType is spelled as kiro-cli spells it (BuilderId, IamIdentityCenter,
ExternalIdP, Social<Provider>), so cloud/login_target.parse_whoami_output and
identity_matches_target read a vault identity and a kiro-cli one through one parser.
An SSO-OIDC sign-in records the start URL it was begun against on the stored token
(KasToken.extra["start_url"], written by _poll_oidc): it is configuration, not a
credential, and it is the one field that tells one organisation's Identity Center
sign-in from another's. Every refresh (auth/refresh.py's three builders) carries
extra onto the renewed token, so the claim survives the token it was recorded on. Tokens stored before it was recorded carry none, and a
whoami without it is read as "an Identity Center sign-in of an unknown
organisation", never as Builder ID.
Sign-out generation. The service's in-memory epoch stops a login begun in THIS
process from re-filling a vault a sign-out in this process emptied. kirocrew kas logout is a second process over the same vault, so the store carries a marker beside
the refresh-rejected ones (TokenStore.signout_generation / bump_signout_generation,
kas/signed-out, a fresh random value per sign-out): every begin_* snapshots it, every
sign-out bumps it after the slots are deleted, and _persist_and_finish compares the
two before it writes. Compare-and-save (with the replaces slot deletions of an
account switch) and delete-all-and-bump each run under one store-wide flock (TokenStore.with_signout_lock, kas/signout.lock, taken outside any
identity's refresh lock), so a sign-out cannot land between a login's compare and its
write. kirocrew kas logout runs the same sign-out over an empty vault too, so the
generation moves even when nothing was stored. A mismatch is terminal for that login
({"status": "error", "code": "signed_out_during_login"}, the entry is dropped);
POST /api/kas-login/poll answers it as the same coded 409 the begin handlers answer
for the in-flight case, so the card ends the sign-in and offers Start over instead of
restarting the provider on the device flow as it does for an ordinary terminal loopback
answer. Unlike the refresh-rejected marker this one is not best-effort: it is the
fence itself, so a bump that cannot be written raises TokenStoreError and the
sign-out reports failure rather than publishing "signed out" while a pending approval
can still undo it.
Sign-in generation. Two accounts of one kind (Google A, then Google B) can come
back with the same profileArn, so none of the claims auth/bridge.vault_identity_fingerprint
hashes tells them apart. The store carries a second marker beside the sign-out one
(TokenStore.signin_generation / bump_signin_generation, kas/signed-in, a fresh
random value per sign-in) that _persist_and_finish bumps right before it saves the new
credential, inside the same flock; a token refresh does not bump it. The fingerprint
folds the marker in when it is set, so both of its readers (the KAS bundle-route model
catalog and the pre-turn identity sweep) see every completed sign-in as an account
change; a same-account re-sign-in therefore turns the catalog cold and retires sessions
once. A vault no sign-in has marked yet keeps the fingerprint it had. The bump is
not best-effort: a marker that cannot be written fails the login with
token_store_failed before the credential is saved, since a saved sign-in the
fingerprint cannot see would keep serving the previous account's state; a save that
fails after the bump leaves only a moved marker, which reads as an account change.
The fingerprint reads the token and the marker together under the sign-out lock, so
it never pairs the previous account's token with a marker a login has just moved.
The remote crew uses exactly these verbs: kirocrew cloud login|logout and the
launch wizard run their sign-in scripts on the instance over SSM, and every script
asks the box's own kirocrew kas route which program to drive
(cloud.md § login_vault.py). The local machine never reads the remote
config and never holds the remote credential. The aws_control crew container has no
sign-in surface of its own -- its identity arrives from Secrets Manager into the
vault -- and on the bundle route it skips kiro-cli's store seed and requires the
engine instead (aws-control.md).
- Builder ID device-code flow through the vault, from a shell (
kirocrew kas login --provider builder_idin an isolated data home, no kiro-cli):RegisterClientandStartDeviceAuthorizationwere accepted by the liveoidc.us-east-1.amazonaws.comand the verification URL + user code were printed. The approval half (a human signing in to the printed URL) and the resultingCreateTokenhave NOT been run live; IdC and External IdP remain unit-tested only. - Social device-code flow: validated end-to-end — a stdlib-only Python client
(no kiro-cli) obtained a real Google
{accessToken, refreshToken, profileArn}via/oauth/device/authorization→ user browser approval →/oauth/device/poll. Confirms the portal/service accept a non-CLI caller identified only byUser-Agent: Kiro-CLI. - Social loopback flow: portal
GET /signinaccepts our params (HTTP 200) and renders the login page; full loopback token exchange not yet run end-to-end. - Builder ID / IdC / External IdP: contract implemented from source and covered by unit tests with a mocked HTTP session; not yet exercised against the live endpoints.
- Unit tests:
test/test_kas_auth_{store,device,flows,helpers,shape_idp}.pycover the store (perms, priority, expiry, invalid-token drops), the device state machine, SSO-OIDC polling, all three refresh paths + the single-flight lock + peer recovery, the KasAuthProvider contract (incl. the refresh-token-never-leaks assertion), PKCE/URL construction, shape→transport selection, external-IdP authorization/exchange, and the bridge seam. black / isort / flake8 / mypy clean.
- Live-endpoint validation of the approval and token half of Builder ID, and of IdC / External IdP end to end (only the social device flow is proven against the real service; Builder ID is proven up to the device prompt).
- The loopback flow has a dashboard driver:
POST /api/kas-login/loopback(api_kas_login_begin_loopback) starts the PKCE loopback sign-in and returns the portal URL plus the polling handle. A coded 409loopback_unavailable(the install shape does not support loopback, or every allowlisted port is busy) sends the client to the device flow.POST /api/kas-login/cancelabandons a pending sign-in and releases the loopback callback port at once instead of at its deadline. - Wiring
KasAuthProviderto the running engine is done through the kiro-cli relay (acp/kas_host_auth.py+ the_kiro/auth/getAccessTokenhandler onAcpRuntime's reader loop). Verified end-to-end against a real kiro-cli release (2.21.0, isolatedHOMEso kiro-cli's own store was empty):kiro-cli acp --agent-engine v3with no--auth-method→ the engine's credential request is the first frame the host receives → host answers with a real OIDC credential →initialize,session/new,session/promptcomplete withstopReason=end_turnand the model's reply (getAccessToken_calls=1). The refused path was measured the same way: with the host answering every callback-32000 "not signed in to Kiro Crew", the engine does not wedge —initializeandsession/newstill complete, it re-asks on each attempt, andsession/promptfails-32000with its own "not signed in … Please sign in and retry" (ModelRegistryUnauthenticatedError/TokenExpiredError), whichacp/transport_errors.py's auth-failure vocabulary now recognizes so the dashboard renders the sign-in prompt rather than a raw error. - A Crew sign-out deletes the vault entry under the identity's refresh lock and
retires running identity-store processes (
dashboard/handlers/kas_login.py), so neither a refresh in flight nor a process holding the old access token in memory outlives the logout. The bundle-route model picker needs nothing from the sign-in service: its recording carries the vault identity fingerprint the producing session's request went out under, and it is served only while the vault still names that account, so a sign-in or sign-out from the dashboard or fromkirocrew kas login/kas logout(cli_kas_login.py) turns it cold (model-selection.md). The dashboard drops its own copy as well: the sign-out button (pages/developer/KiroSignInCard.tsx) and the authorized sign-in (components/KasLoginGate.tsx) drop the browser's model-list caches (clearCachedModels, a reset of['available-models']), because that query is otherwise refetched only when a session spawns. - The dashboard surfaces that NAME the signed-in account read the vault, never
kiro-cli whoami, whenever the vault is the harness's credential (the KAS bundle route whatever the vault holds, or the relay route with a usable Crew sign-in -- the usage poll's_vault_owns_usageverdict): the credit reading'saccount_typelabel and the identity doorfetch_local_identityboth come fromauth/bridge.vault_identity_claims, oneresolve()that yields the identity fingerprint and the token-free slot, provider and recorded start-URL claims together, rendered byauth/whoami.whoami_document_for-- the same writerkirocrew kas whoamiprints -- and mapped onto the dashboard's field names bydashboard/handlers/kiro_vault_identity.py. So a Crew sign-in shows its provider kind and, for an Identity Center sign-in that recorded one, its portal host (a token stored before the start URL was recorded shows it after one re-login). The vault stores no e-mail: the vault-credentialGetUsageLimitscall sendsisEmailRequired: true, as kiro-cli does, and the reading carriesuserInfo.emailasemail(the discovered-candidate path does not ask; its e-mail is whoami's). A 400 answer to that call is retried once without the flag, so a service that refuses it loses only the e-mail, not the reading. The identity door keeps whoami's three-way answer:{}(nothing to inherit) only for a vaultTokenStore.holds_no_identityproves empty,None(unknown) for one that did not read or holds an entry that will not decrypt, so an unreadable vault never proposes the default Builder ID target to an Identity Center operator. Spec: learn-cron-dashboard.md, GET/api/sessions/usage. - Known limit, by decision: the spawn-time probe (
auth/bridge.vault_holds_identity) accepts a stored identity whose access token is live or which carries a refresh token; it cannot know without a network call that an issuer will reject that refresh token, nor does it check the local inputs a refresh needs (KasToken.refresh_blocker: stored client credentials, a token endpoint) -- a refresh that cannot even be attempted raisesauth/refresh.RefreshBlocked, as permanent as a rejection but with no issuer asked and so no marker recorded. When a refresh IS refused (issuer answers 400/401/403,auth/refresh.RefreshRejected), the refresher records a token-free marker beside the vault (TokenStore.mark_refresh_rejected, cleared by any new credential landing in the slot), and that marker is whatkirocrew doctor(crew vault:line),KasLoginService.status()(refresh_rejected) and the dashboard's Kiro sign-in card report as "sign-in expired -- sign in again". The marker does NOT feed the spawn decision: a lapsed Crew identity is told to the user (the card, and the agent's "not signed in" error row with its sign-in deep link), never silently handed back to whateverkiro-cli loginholds. Automatic demotion to cli-owned after a persistent refresh failure is therefore not a gap to close but a behaviour deliberately not built (see #9772). The spawn owner is the shared sign-in resolver's pick (RFC crew-enterprise-edition D4,ossorder, amended 2026-10-30; delivered by #26841): any stored vault entry, including one whose access token has expired with no refresh token, and a vault that cannot be read, keeps the spawn Crew-owned and reports "not signed in"; only an empty vault hands it to kiro-cli. Removing the Crew sign-in (kirocrew kas logout) is how a user goes back to kiro-cli's. - The product entry point for the flow is the Kiro sign-in section on Settings >
Agent Harness (
website/src/pages/developer/KiroSignInCard.tsx,compactform), rendered byAgentBackendTabINSIDE the KAS row's detail and only while KAS is a backend that switch offers -- the stored identity is consumed by the KAS relay alone, so a build or policy that cannot select KAS has nothing to sign in for, and a row that is not KAS has no use for it. The section embeds the same viewsKasLoginGaterenders (KasLoginEmbedded, card chrome instead of the scrim + aside door; in that chrome the four provider choices are outlined and sit in a two-column grid, none accent-filled, because the detail's own primary button is "Use {{name}}", fromcomponents.kiroPrerequisiteGate.use_agent) and adds a signed-in summary (provider, expiry, renewability -- never a token) with sign-out and sign-in-again. It is reachable from the chat error row anAcpAuthRequiredturn produces (chat_utils.AUTH_REQUIRED_KIND→ "Sign in to Kiro", navigating toKIRO_SIGN_IN_PATH=/settings/agent?highlight=key:kiro-sign-inwith the colon percent-encoded, frompages/developer/kiroSignInLink.ts, whosehighlightrings the card through theuseSettingHighlighthook SettingsPage mounts; the card's older home,/developer?tab=agent-backend, is forwarded there by the/developerredirect with thehighlightkept) and from the KAS remedy strings inagent_sdk/host_auth.py. Its intro sentence names the backend ("Used only by the Kiro Agent backend") and says Kiro CLI keeps its own kiro-cli login, because the card sits under a switch that also lists Kiro CLI. It is deliberately NOT on Settings > Overview and not indexed into Settings search: a provider chooser on the landing page read as a required step to every user, first-run installs included, and Overview carries no signpost to it. The switch and card are a Settings tab of their own because first-run setup offers agents other than Kiro CLI, so a user who set up with one of those can switch agents later.KasLoginGateitself is still not mounted at the app root; the full-screen form stays available for that. - The persistent signal for a lapsed sign-in is the app-level Kiro sign-in
notice (
website/src/components/KiroSignInNotice.tsx, mounted inApp.tsxabove every route besideCrashReportNotice), because the card above lives on a page nobody keeps open. It is a banner, not a top-bar control: the top bar's action groups are at the two-control cap. It renders only whileagent.acp_backendiskas, a sign-in is stored, and the card's own verdict (signInLapsedinpages/developer/kiroSignInState.ts, shared by both:!usable || refresh_rejected) calls it lapsed; it is hidden on Settings > Agent Harness itself, where the card shows the same state. Every lapsed shape it draws is anErrorNoticewith the agent hand-off, an "Open sign-in settings" button and dismiss, so an expiry with nothing to renew it and a renewal Kiro refused read at the same weight (in both the agents' credential requests are refused, or will be); the title and text say which one happened. Because the renewal tick only asks Kiro inside the refresh margin, a refusal is usually recorded on a token that is alreadyexpired(whileusablestays true, since a refresh token is stored); the refused notice then says the agents cannot run, and only a refusal on a token outside the margin says they will stop. The button asks the page's leave guard and then deep-links toKIRO_SIGN_IN_PATH; dismissing hides the notice for the current cause until the page reloads (a refusal that has since expired is a new cause). A failed status read on a KAS gateway renders the same way under "We could not check sign-in status", with a plain-language line saying what to do (the server's error goes to the hand-off, not the visible text), since the sign-in then goes unchecked. A config read that fails before any good read shows "Could not read the dashboard settings" with the hand-off and no sign-in button or sign-in claim: it cannot say whether KAS runs the agents, and kiro-cli and Claude have no Kiro sign-in. It stays hidden while the gateway is offline or asks for a token, since the offline capsule and the token banner already name that cause and its fix. A failure after a good read shows nothing, since the query keeps that read's backend, so a KAS gateway goes on reading the status. If the notice itself fails to load or render, its error boundary shows "Part of the dashboard could not load" with the hand-off (KiroSignInNoticeFallback, outside the notice's lazy chunk). It reads the same token-freeGET /api/kas-loginstatus under the same['kas-login']query key the card and flow use, polling once a minute only on a KAS gateway (another backend never reads it), so the refusal marker the renewal tick records shows on the next read and a new sign-in or a successful renewal clears it.