@foundation0/auth

What this package is for

TypeScript SDK for Authorization and Delegation Layer workflows. Use it when you want one root client for capabilities, verification, receipts, services, revocations, pricing, sidecar, batches, release validation, data-lifecycle helpers, and local Auth ID session workflows.

Install

pnpm add @foundation0/auth

Root import

import { createAuth } from "@foundation0/auth";

const auth = createAuth();
const result = await auth.verify.token({
  capability: process.env["F0_CAP"] ?? "<paste capability token>",
  servicePid: "did:example:svc:reference-ep",
});

console.log(result.ok);

Auth ID runtime

The root client also exposes local Auth ID lifecycle helpers through auth.id.*.

import { createAuth } from "@foundation0/auth";

const auth = createAuth();

const created = await auth.id.create({
  identityId: "local-dev",
  providerKind: "local-hd",
  password: process.env["AUTH_ID_PASSWORD"] ?? "dev-password",
});

const identities = await auth.id.list();
console.log(created.identity.identity_id, identities.identities.length);

Hero workflows

• issue or delegate a capability through auth.capabilities.*
• verify tokens and bound operations through auth.verify.*
• validate receipts, pricing, and batches through auth.receipts.*, auth.pricing.*, and auth.batches.*
• resolve descriptors and publish revocations through auth.services.* and auth.revocations.*
• call a remote sidecar or validate release/data workflows through auth.sidecar.*, auth.release.*, and auth.data.*

Public Surface

• root client: createAuth(options?)
• stable subpaths:
  • @foundation0/auth/client
  • @foundation0/auth/services
  • @foundation0/auth/errors
  • @foundation0/auth/testing
  • @foundation0/auth/json
  • @foundation0/auth/zero
  • @foundation0/auth/compat
  • @foundation0/auth/compat/deprecations
  • @foundation0/auth/compat/error-bridge
  • @foundation0/auth/compat/helper-aliases
  • @foundation0/auth/compat/option-normalizers

What The Client Exposes

• auth.capabilities
• auth.verify
• auth.receipts
• auth.services
• auth.revocations
• auth.pricing
• auth.sidecar
• auth.batches
• auth.release
• auth.data
• auth.id

Zero Profile Resolver Foundation

@foundation0/auth/zero is the public compatibility wrapper for the SDK-local zero primitives in packages/adl-sdk/src/zero. It exposes the profile-gated PROF-ZERO-001 coordinate resolver foundation for deployments that publish pinned zero-profile evidence. It validates canonical compact zc:c1.<xb64u>.<yb64u>.<zb64u> principals, keeps long coord:v1:<x>:<y>:<z> coordinates only in evidence and binding fields, and rejects legacy zero:coord:v1:<x>:<y>:<z> aliases unless a release-manifest migration adapter explicitly enables allowZeroCoordMigrationAlias. Enabled aliases are normalized back to compact canonical principals before resolution. It also validates canonical coordinate-scoped z:c1.<xb64u>.<yb64u>.<zb64u>/<service-code> ResourceURIs with the compact service-code table (s, g, r, m, t, b, i, x, a). Legacy f0:zero:coord:v1:<x>:<y>:<z>/<zero-class> aliases are rejected unless an explicit migration adapter enables allowZeroResourceMigrationAlias, and enabled aliases normalize back to compact z:c1.* resources before authorization. The zero layer also validates strict ZeroEvidenceBundle and ZeroInvocationBinding projections, CFG-048 freshness, CFG-049 evidence-source pins, and accepted signer PID resolution. The resolver output is only an Auth authorization input; it does not assert external Stream replay validity, semantic truth, Storage availability, Index completeness, materialization correctness, DCPS settlement, or real-world identity ownership.

Use bindZeroInvocationMaterial(...) to compute the deterministic binding_hash_b64 for the claimed operation family before executing work, and verifyZeroInvocationBinding(...) or executeWithZeroInvocationBinding(...) to fail closed before side effects when the supplied invocation projection is missing, malformed, paired with the wrong body material kind, or replayed against different material. The body-binding helpers cover Stream event submission, connection and attachment publication, storage or gateway admission, Index advertisement, materializer execution, and AI or agent execution.

Use buildZeroNonAuthorityReceiptEvidence(...) and describeZeroDenial(...) when emitting zero-profile receipts or logs. They keep the Auth decision scoped to authorization inputs and denial reasons, and explicitly leave Stream replay, semantic truth, Storage/Index completeness, DCPS settlement, and materializer correctness to downstream zero-stack validators.

Choose The Right Namespace

| Workflow | Preferred SDK path | | --- | --- | | issue or delegate capability | auth.capabilities.issue(...), auth.capabilities.delegate(...) | | verify a token string | auth.verify.token(...) | | verify a concrete request or operation | auth.verify.call(...) | | verify a signed receipt | auth.receipts.verify(...) | | resolve or publish a service descriptor | auth.services.resolve(...), auth.services.publishDescriptor(...) | | check or publish a revocation | auth.revocations.check(...), auth.revocations.publish(...) | | fetch or verify pricing | auth.pricing.fetch(...), auth.pricing.verify(...) | | call a remote sidecar | auth.sidecar.* | | build or export a receipt batch | auth.batches.build(...), auth.batches.export(...) | | validate a release manifest | auth.release.validate(...) | | erase managed evidence | auth.data.erase(...) |

Release-manifest validation uses the shared SDK validator. When a manifest claims project-specifications.v1.6.0.md, PROF-ZERO-001, PROF-ID-001, or implementation-plan v1.6.0.5, requiredEvidenceRefsForRelease(...) exposes the complete inherited TC-ZERO-*, TC-V1603-*, TC-V1604-*, and TC-V1605-* gate family used by the public SDK and CLI wrappers. Corrective evidence refs must include gate/task identity, local artifact path/hash, command or report ref, transcript path/hash, timestamp, status, and retained content hash, and matching task-lineage paths for corrective gates. Pre-final HOLD validation may omit only TC-V1605-FULL-CONFORMANCE when the manifest declares release_status: "HOLD" and that gate in pending_gate_ids; final manifests must include the full gate family.

For v1.6.0.11 final manifests, the shared validator also requires a schema-complete public release manifest and rejects provenance-shaped subsets stored under release/manifests/. Separate release/package provenance JSON must live under release/provenance/ and be referenced by the full manifest. The public Auth wrapper re-exports the SDK-owned REQUIRED_V16011_FINAL_EVIDENCE_IDS catalog used by final manifest validation.

Docs and examples

• SDK quickstart
• Verification cookbook
• SDK reference
• Auth rename baseline
• Migration guide
• Validated example

Compatibility

Compatibility alias: adl-sdk remains available for migration-safe installs and repo-local compatibility coverage. Compatibility aliases such as createAdl() and the @foundation0/auth/compat helpers remain available for migration support, but new installs and docs should target createAuth() from @foundation0/auth first.

Troubleshooting and reference

• Troubleshooting index
• SDK reference
• Unified surface migration

Local validation

• pnpm --filter @foundation0/auth test
• pnpm --filter @foundation0/auth typecheck
• pnpm --filter @foundation0/auth build
• pnpm --filter @foundation0/auth type-regression
• pnpm --filter @foundation0/auth api-report
• pnpm docs:sdk-reference
• pnpm docs:sdk-reference:check