aios/docs/gitops/task-identity-overlay.md

Task-scoped identity overlay

Purpose

The overlay resolves a bootstrap deadlock where the global bearer registry maps one secret to more than one identity and no active, non-wildcard Owner credential is available.

It does not modify gitops.tokens, enable a disabled credential or add a long-lived Owner scope. A root-governed issuer creates a fresh random bearer that is accepted only by a localhost-only staging API and only for one exact task binding.

Fixed V2R1C6 binding

• task: V2R1C6_TASK_SCOPED_WRITER_PROVISIONING
• repository: aios/aios
• base ref: refs/heads/main
• base OID: 875d41c3101093149414292067fd700dc214d4d3
• target branch: agent/v2r1c6-mainline-reconciliation-20260805
• maximum credential lifetime: 900 seconds
• one-time use: required

Security model

1. Issuance is a root-only, audited bootstrap operation.
2. A cryptographically random bearer is written to a mode-0600 runtime file.
3. Metadata contains only the SHA-256 digest of the bearer.
4. The issuer checks configured active secret references for a hash collision.
5. The API ignores the global bearer registry.
6. The request must exactly match the configured task, repository, base and target branch.
7. Main, tag, Baseline, production, branch deletion, force push and repository administration remain explicitly denied.
8. The credential is deleted after success, failure, revocation or expiry.
9. The Owner Authorization Broker remains responsible for the audited authorization event, signed grant, validator and provisioner chain.

Components

• task_identity_overlay.py: state machine and broker integration.
• aios_task_identity_overlay_cli.py: root-only issue/status/revoke CLI.
• aios_task_identity_overlay_api.py: localhost-only overlay API.
• call_task_identity_overlay.py: client that keeps the bearer out of argv.
• smoke_task_identity_overlay.py: HTTP end-to-end smoke test.

Expected lifecycle

root-governed issue
  -> unique task secret
  -> localhost overlay authentication
  -> Owner Authorization Broker event
  -> signer
  -> validator
  -> one-shot writer provisioner
  -> READY_FOR_CODE_AUTHORING
  -> overlay secret removed

Failure states

The overlay fails closed on:

• base or branch mismatch;
• request-field expansion;
• production capability request;
• wildcard scope metadata;
• token collision;
• token replay with a different request;
• expired or terminal credential;
• provisioner, validator or signer failure;
• metadata digest failure;
• state or secret symlinks;
• directory permission expansion.

A failed provisioning attempt revokes the overlay credential. A new overlay can be issued for the same fixed task without changing the Owner business approval.