[saurabhmaheshwari-obin]

What

A declared module route /v1/<alias>/* admits a host-minted headless operation context with no bearer, on the gateway's workload endpoint only.

Today a composed workload with a headless binding to a declared module can mint its operation context at /modules/_operation-context, but the route then refuses it, because ext_authz requires a person's bearer. That leaves a solution's release-declared headless operation with no host path at all (for example, publishing its own definitions to a module at release), since a solution may reach a module only through the gateway.

Accounts, the capability's issuer, makes the admission decision through a new internal RPC, AdmitWorkloadOperation. It is an allow-list of exactly one shape: the context StartModuleOperationTask mints.

Also in this PR:

• accounts: a person's capability always stays sealed to its audience's installation. StartChildSession used to let a child for another module's audience keep the parent's seal.

This replaces #1243, which targeted a patch line off v0.0.105. That line has no consumer, so this PR targets main.

How the arm decides

The gateway selects the arm only when all of these hold:

• no Authorization header and no Cookie;
• the request arrived on the workload listener, plus the XFCC presenter on a cell;
• exactly one capability header, and no Connection option names it;
• core's inspection passes for the route's alias, and the alias is never module-capabilities.

Every other request takes the existing path unchanged.

On the arm:

• Strip first: identity headers, Authorization, Proxy-Authorization and XFCC are removed before anything else runs.
• Rate limit: keyed workload-operation:<tenant>. It fails closed and runs before the accounts call.
• Admission: one call to AdmitWorkloadOperation{work_context, alias, target_id}, bounded at 2 s.
  • Admitted: forward.
  • TARGET_NOT_INSTALLED: 403.
  • Any other refusal, or an invalid argument: 401.
  • An error, a timeout, no client, or an answer naming a different tenant or seal than the one inspected: 503.
• Forwarding: no bearer, and no installation header stamped. The callee verifies the capability itself at full strength. An upstream failure gets a static 502.
• Logging: every admit and refusal is logged with the issuer's reason, never the token.

What accounts admits

AdmitWorkloadOperation is internal-only, with the same policy block as ListInstallations. It checks the internal credential before it validates the request.

• It reads the capability back through core's issuer read-back (Authority.ReadBack, audience = alias). The read-back checks signature, window, revision and the live seal, and it never touches the replay store, so no nonce is spent.
• It admits only the StartModuleOperationTask shape:
  • a service owner that is a declared module principal, and not the alias's own;
  • sealed to that principal's live, active installation;
  • no actor chain, grant hop, operation binding or parent session;
  • idempotent, with a window no longer than the 60 s TTL;
  • at least one scope.
• It also answers the target: the target must be installed (ACTIVE) in the tenant, and the seal must not be one of the target's rows.
• Refusals: NOT_INSPECTED, OWNER_NOT_SERVICE, NOT_OPERATION_CONTEXT, OWNER_IS_TARGET, SEAL_NOT_OWNERS, TARGET_NOT_INSTALLED, SEAL_ON_TARGET and NOT_CURRENT (an uninstalled module, a changed tenant, or a revoked seal).

Person-owned capabilities are all refused, whatever their seal. That includes source-operation contexts, installation tasks, and installed content-read and module_actor children.

Contract changes

• New accounts-owned saas/accounts/v1/workload_operation_admission.proto holds the request, the response and the refusal enum. work_contexts.proto imports it, and it adds WorkContextService/AdmitWorkloadOperation. The gateway vendors the file byte-identical, as it does its other accounts protos.
• Additive only; buf breaking against main passes.
• @codefly-dev/saas-sdk goes to 0.3.36 for the new generated messages, because the kit-version gate requires the bump.
• Naming-gate size cap (module/tools/naming-gate.mjs), its own commit:
  • The new RPC grows generated/service-catalog.json to 524,580 bytes, past the gate's 512 KiB cap, so the gate refused to scan it. This PR raises the cap to 1 MiB, so the file is still scanned.
  • Alternatives: allowlisting the file, which would stop scanning it entirely, or splitting the generated catalog, which is a structural call for maintainers.
  • The commit stands alone, so it can be reverted or replaced without touching the rest.

Tests

• accounts:
  • TestEveryMintHasAWorkloadOperationVerdict: every token-minting RPC and every binding mode, each minted through a real path, gets an asserted verdict. Only StartModuleOperationTask admits.
  • TestWorkloadOperationTableNamesEveryMintAndOwnerKind: fails when any of these appears without a row in that table:
    • a token-returning accounts RPC, detected transitively through the response;
    • a signing call on *workcontext.Authority, detected by type, including method values and package-level vars;
    • a principal kind.
  • TestEveryRemintOfAServicePrincipalsParentHasAVerdict, plus TestADelegatedExchangeRefusesAModuleOperationContextAsItsParent in pkg/infra against Postgres: a module operation context presented as a parent to every re-mint path is refused.
  • TestAdmitWorkloadOperationConsumesNothing: a single-use capability admitted three times still verifies once at the callee.
  • TestAdmitWorkloadOperationIsInternalAndFailsClosed.
  • TestAPersonsCapabilityIsSealedToItsAudiencesInstallation and TestStartChildSessionRefusesAPersonsChildForAnotherAudiencesInstallation.
• auth-gateway: TestModuleRoute_TheBearerLessArmAdmitsOnlyWhatTheIssuerAdmits and the arm's selection, strip order, limiter-before-call, 401/403/503 mapping, Connection, two-carrier, 502 and nil-client cases. Each refusal case fails against the code before its fix.
• Gates run locally:
  • go vet and go test on the changed packages: accounts pkg/adapters, the pkg/infra installation and exchange tests, and auth-gateway;
  • buf lint and buf breaking, and codefly generate contracts --check;
  • kit-version, release-gates, interface-docs, naming gate, authz coverage and check-boundaries.sh.

Rollout

Deploy accounts before the gateway. A gateway that calls an accounts without the RPC answers 503 and admits nothing, so it fails closed.

Known limits

• An admitted context is a bearer capability for its window (60 s or less), pinned to one audience.
• The arm does not bind the presenter's workload identity to the owner. On a cell the presenter must still be a mesh workload.
• The admission rule copies the shape StartModuleOperationTask signs. The durable form is core-side: core's Inspected would expose the owner kind (or a mint-stamped marker) so a hop can check it directly. That reverses core's "a hop never reads the principal", so it is left for a design discussion.

Review

• Codex at xhigh, twice, plus security, architecture and an executing bug-hunter.
• They found, and this PR fixes:
  • an earlier seal-based classification that admitted person-owned shapes, replaced by the issuer allow-list;
  • a hand-built inspection, replaced by core's issuer read-back;
  • an admission split across two RPCs;
  • a Connection option naming the capability header;
  • credential-before-validate ordering;
  • 503 versus 401 classification for uninstalled modules;
  • gaps in the guard tests' mint detection.
• Antoine: host code. Review requested.

Live

Local run with CLI 0.1.207 and this head (3b16ae2d3) as the host. A solution's release publisher mints at /modules/_operation-context and posts its bundle to /v1/<alias>/definitions:publish on the workload endpoint, with no bearer.

• Admitted: the gateway logged reason=workload_operation_admit naming the alias, the tenant, the task, the solution's own installation as seal, and presenter local. The module created 5 definitions.
• Replay after a full reboot: nothing created; same digest.
• A bundle naming another repository: the gateway admitted it and the module refused it with 403. Authorization stays the callee's.
• Target not yet installed in the tenant: 403 target_not_installed, then admitted once it was installed.
• Accounts paused: 503 authority_unavailable at the 2 s bound. 200 once it resumed.
• Refusals through the running gateway, all 401:
  • the operation context on the public rest endpoint;
  • a person's StartTask capability presented with no bearer on workload (owner_not_service);
  • a context minted for another audience;
  • two carrier headers (capability_not_single);
  • no carrier;
  • a Connection option naming the carrier (connection_names_capability).
• The person bearer path with a capability: unchanged. 200 once the person is entitled.

Not verified live (unit-tested):

• the remaining refusal reasons;
• a 429 from the limiter;
• cell mode (presenter through the mesh);
• a second declared module.

Second consumer

Any other solution with a release-declared headless operation uses the same arm and copies nothing. Any other edge would call AdmitWorkloadOperation rather than reimplement it. Modules keep calling each other directly in the mesh.

🤖 Generated with Claude Code