@cotal-ai/auth 0.0.0 → 0.11.0

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAOrB;;kGAEkG;AAClG,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAwBD,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAOpE;AAED;;+DAE+D;AAC/D,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAOvG;AAWD;6CAC6C;AAC7C,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAclF;AAED;;;kGAGkG;AAClG,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAevF;AAUD,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAOnE;AAED;sFACsF;AACtF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAUzD;AAMD;;;;2EAI2E;AAC3E,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAMhE;AAED;;;6BAG6B;AAC7B,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAoBvE;AAMD;;;;iCAIiC;AACjC,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAMD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAMpE;AAED;;+CAE+C;AAC/C,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAGpE;AAMD;;;;;kFAKkF;AAClF,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,6FAA6F;IAC7F,GAAG,EAAE,MAAM,CAAC;CACb;AAMD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAM5E;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CAG5E;AAED;mDACmD;AACnD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtD"}

package/dist/store.js

@@ -0,0 +1,208 @@
+/**
+ * On-disk persistence for a space's USER-AUTH material, under the same `.cotal/auth/` dir as the
+ * space trust material (explicit-dir APIs, the auth-paths posture: the caller picks the dir, nothing
+ * here discovers paths ambiently). Everything is generate-on-first-use and STABLE thereafter — the
+ * callout account identity, the issuer signing keys, and the owner-derivation secret must survive
+ * restarts, or previously-minted credentials/owners silently break:
+ *
+ *  - `callout.json` — the dedicated auth-callout account ({@link CalloutAuth}: account + signing key,
+ *    callout service creds, deny-all sentinel creds, xkey). Regenerating it would orphan the account
+ *    the broker config preloads; minting it the first time needs the FULL SpaceAuth (operator seed).
+ *  - `issuer.json` — the Cotal user-bearer issuer: its pinned `iss` string plus the serialized
+ *    Ed25519 signing keys (private JWKs) and the active kid. Losing these kills every outstanding
+ *    bearer (rotation is `rotate`/`retire` on the loaded issuer, then {@link saveIssuerFile}).
+ *  - `owner-secret.json` — the per-space owner-derivation secret (32 random bytes). REGENERATING IT
+ *    RE-KEYS EVERY OWNER in the space (same human → different `u_…`), which is a migration, never an
+ *    accident — hence load-or-create with no overwrite path.
+ *
+ * All files 0600 under a 0700 dir (core's secret-fs helpers), atomic writes, versioned JSON with
+ * fail-loud parsing (the login session-cache posture: a torn/hand-edited credential file surfaces as
+ * one legible sentence, never a raw SyntaxError downstream).
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { mkSecretDir, writeSecretFileAtomic } from "@cotal-ai/core";
+import { createCalloutAuth } from "./callout.js";
+import { normalizeIdpUrl } from "./login.js";
+import { createUserTokenIssuer, exportSigningKey, generateSigningKey, importSigningKey, } from "./issuer.js";
+const CALLOUT_FILE = "callout.json";
+const ISSUER_FILE = "issuer.json";
+const OWNER_SECRET_FILE = "owner-secret.json";
+const STORE_VER = 1;
+/** The pinned `iss` for a space's Cotal user bearers — a stable URN, deliberately NOT the auth
+ *  service's URL (the service port is ephemeral; an issuer pin must never change across restarts).
+ *  Both the issuer (mint) and the callout (validate) take it from here — one source, no drift. */
+export function spaceIssuer(space) {
+    if (!space)
+        throw new Error("spaceIssuer: a space is required");
+    return `urn:cotal:auth:${space}`;
+}
+/** Fail-loud versioned-JSON read: a missing file is undefined; a torn/edited/unknown-version file is
+ *  a legible sentence naming the file and the recovery, never a raw parse error downstream. */
+function readStoreFile(path, what) {
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${path}: the ${what} file is not valid JSON (${e instanceof Error ? e.message : String(e)}) - restore it from backup; regenerating breaks existing credentials`);
+    }
+    if (parsed === null || typeof parsed !== "object" || parsed.ver !== STORE_VER)
+        throw new Error(`${path}: unknown ${what} version ${String(parsed?.ver)} (expected ${STORE_VER}) - refusing to guess at credential material`);
+    return parsed;
+}
+/** Load the persisted callout account material, or undefined if this space never enabled user auth. */
+export function loadCalloutAuth(dir) {
+    const f = readStoreFile(join(dir, CALLOUT_FILE), "callout account");
+    if (!f)
+        return undefined;
+    const c = f.callout;
+    if (!c?.account?.pub || !c.account.jwt || !c.calloutCreds || !c.sentinelCreds || !c.xkey?.seed)
+        throw new Error(`${join(dir, CALLOUT_FILE)}: malformed callout account material - restore it from backup; regenerating orphans the preloaded auth account`);
+    return c;
+}
+/** Load-or-create the callout account: first call on a space mints it (operator seed required)
+ *  and persists; every later call returns the SAME account, so the broker config preload and
+ *  previously-issued sentinel creds stay valid. Idempotent. */
+export async function ensureCalloutAuth(dir, input) {
+    const existing = loadCalloutAuth(dir);
+    if (existing)
+        return existing;
+    const callout = await createCalloutAuth(input);
+    mkSecretDir(dir); // harden BEFORE the secret lands
+    writeSecretFileAtomic(join(dir, CALLOUT_FILE), JSON.stringify({ ver: STORE_VER, callout }, null, 2));
+    return callout;
+}
+/** Load the persisted issuer (all published kids live; the persisted active kid signs), or undefined
+ *  if this space never enabled user auth. */
+export async function loadIssuer(dir) {
+    const f = readStoreFile(join(dir, ISSUER_FILE), "issuer key");
+    if (!f)
+        return undefined;
+    if (!f.issuer || !Array.isArray(f.keys) || !f.keys.length || !f.activeKid)
+        throw new Error(`${join(dir, ISSUER_FILE)}: malformed issuer key file - restore it from backup; regenerating kills every outstanding bearer`);
+    const active = f.keys.find((k) => k.kid === f.activeKid);
+    if (!active)
+        throw new Error(`${join(dir, ISSUER_FILE)}: active kid ${f.activeKid} is not in the key set - restore it from backup`);
+    // createUserTokenIssuer starts with one active key; rotate() adds the rest (each rotate re-points
+    // active, so feed the non-active keys THROUGH rotate and finish on the persisted active kid).
+    const issuer = createUserTokenIssuer({ issuer: f.issuer, key: await importSigningKey(active) });
+    for (const k of f.keys)
+        if (k.kid !== f.activeKid)
+            issuer.rotate(await importSigningKey(k));
+    if (issuer.activeKid() !== f.activeKid)
+        issuer.rotate(await importSigningKey(active));
+    return issuer;
+}
+/** Load-or-create the space's user-bearer issuer: first call generates the Ed25519 signing key and
+ *  persists it under the pinned {@link spaceIssuer} `iss`; later calls return the SAME keys, so
+ *  outstanding bearers keep verifying. A persisted `iss` that disagrees with the space's pin fails
+ *  loud (the material belongs to another space/layout — never sign under a mismatched issuer). */
+export async function ensureIssuer(dir, space) {
+    const iss = spaceIssuer(space);
+    const existing = await loadIssuer(dir);
+    if (existing) {
+        if (existing.issuer !== iss)
+            throw new Error(`${join(dir, ISSUER_FILE)}: persisted issuer "${existing.issuer}" != this space's pin "${iss}" - the material belongs to a different space; refusing to mint under it`);
+        return existing;
+    }
+    const key = await generateSigningKey();
+    mkSecretDir(dir);
+    writeSecretFileAtomic(join(dir, ISSUER_FILE), JSON.stringify({ ver: STORE_VER, issuer: iss, activeKid: key.kid, keys: [await exportSigningKey(key)] }, null, 2));
+    return createUserTokenIssuer({ issuer: iss, key });
+}
+/** Load the owner-derivation secret, or undefined if this space never enabled user auth. */
+export function loadOwnerSecret(dir) {
+    const f = readStoreFile(join(dir, OWNER_SECRET_FILE), "owner secret");
+    if (!f)
+        return undefined;
+    const secret = Buffer.from(f.secretB64 ?? "", "base64");
+    if (secret.byteLength !== 32)
+        throw new Error(`${join(dir, OWNER_SECRET_FILE)}: malformed owner secret - restore it from backup; a regenerated secret RE-KEYS EVERY OWNER in the space`);
+    return new Uint8Array(secret);
+}
+/** Load-or-create the per-space owner-derivation secret. There is deliberately NO regenerate path:
+ *  a new secret re-keys every owner in the space (a migration, never an accident). */
+export function ensureOwnerSecret(dir) {
+    const existing = loadOwnerSecret(dir);
+    if (existing)
+        return existing;
+    const secret = randomBytes(32);
+    mkSecretDir(dir);
+    writeSecretFileAtomic(join(dir, OWNER_SECRET_FILE), JSON.stringify({ ver: STORE_VER, secretB64: Buffer.from(secret).toString("base64") }, null, 2));
+    return new Uint8Array(secret);
+}
+// ---- the pinned external IdP ----
+const IDP_FILE = "idp.json";
+/** Load the pinned IdP, or undefined if this space never pinned one. */
+export function loadPinnedIdp(dir) {
+    const f = readStoreFile(join(dir, IDP_FILE), "IdP pin");
+    if (!f)
+        return undefined;
+    if (!f.url || !f.issuer || !f.audience || !f.jwksUri)
+        throw new Error(`${join(dir, IDP_FILE)}: malformed IdP pin - re-pin with \`cotal up --user-auth --idp <url>\``);
+    return { url: f.url, issuer: f.issuer, audience: f.audience, jwksUri: f.jwksUri };
+}
+/** Pin-or-verify the space's IdP. First call REQUIRES a URL (there is no default IdP); later calls
+ *  either omit it (reuse the pin) or must MATCH it — re-pointing a space at a different IdP re-keys
+ *  every derived owner (the issuer is part of the derivation input), a migration this refuses to do
+ *  as a flag side-effect. */
+export function ensurePinnedIdp(dir, idpUrl) {
+    const existing = loadPinnedIdp(dir);
+    if (existing) {
+        if (idpUrl !== undefined && idpUrl !== existing.url)
+            throw new Error(`this space's IdP is pinned to ${existing.url}; --idp ${idpUrl} would re-key every derived owner. ` +
+                `Re-pointing an IdP is a migration - remove ${join(dir, IDP_FILE)} deliberately if you mean it.`);
+        return existing;
+    }
+    if (!idpUrl)
+        throw new Error("user auth needs an IdP on first enable - run with --idp <auth base URL> (Better Auth: <origin>/api/auth)");
+    // Same normalization + scheme guard as `cotal login` (https, or loopback http for dev; no
+    // query/hash/userinfo) — the pin and the login cache must key on the SAME canonical URL.
+    const url = normalizeIdpUrl(idpUrl);
+    const origin = new URL(url).origin;
+    const pin = { url, issuer: origin, audience: origin, jwksUri: `${url}/jwks` };
+    mkSecretDir(dir);
+    writeSecretFileAtomic(join(dir, IDP_FILE), JSON.stringify({ ver: STORE_VER, ...pin }, null, 2));
+    return pin;
+}
+// ---- the auth service's own key projection ----
+const SERVICE_KEYS_FILE = "service-keys.json";
+export function loadServiceKeys(dir) {
+    const f = readStoreFile(join(dir, SERVICE_KEYS_FILE), "service key projection");
+    if (!f)
+        return undefined;
+    if (!f.dataAccount?.pub || !f.dataAccount.signingSeed)
+        throw new Error(`${join(dir, SERVICE_KEYS_FILE)}: malformed service key projection - re-run \`cotal up --user-auth\` to rewrite it`);
+    return { dataAccount: { pub: f.dataAccount.pub, signingSeed: f.dataAccount.signingSeed } };
+}
+/** Write (or refresh) the service's key projection. Idempotent overwrite — the projection carries
+ *  no identity of its own, it IS the (stable) data-account signing material, so rewriting from the
+ *  same space bundle is a no-op in content. */
+export function saveServiceKeys(dir, keys) {
+    mkSecretDir(dir);
+    writeSecretFileAtomic(join(dir, SERVICE_KEYS_FILE), JSON.stringify({ ver: STORE_VER, ...keys }, null, 2));
+}
+// ---- the auth-service runtime discovery file ----
+const SERVICE_FILE = "auth-service.json";
+export function loadAuthServiceInfo(dir) {
+    const f = readStoreFile(join(dir, SERVICE_FILE), "auth service info");
+    if (!f)
+        return undefined;
+    if (!f.url || typeof f.pid !== "number" || !f.cap)
+        throw new Error(`${join(dir, SERVICE_FILE)}: malformed auth service info - restart the mesh (\`cotal down\` then \`cotal up\`)`);
+    return { url: f.url, pid: f.pid, cap: f.cap };
+}
+export function saveAuthServiceInfo(dir, info) {
+    mkSecretDir(dir);
+    writeSecretFileAtomic(join(dir, SERVICE_FILE), JSON.stringify({ ver: STORE_VER, ...info }, null, 2));
+}
+/** Remove the discovery file (daemon shutdown / CLI pre-start scrub) so a stale entry can never
+ *  satisfy a readiness poll for the NEXT start. */
+export function clearAuthServiceInfo(dir) {
+    rmSync(join(dir, SERVICE_FILE), { force: true });
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/token.d.ts

@@ -0,0 +1,68 @@
+import type { CryptoKey, JWTVerifyGetKey } from "jose";
+/** Current normative token-shape version. Bump only with a SPEC change; validators reject
+ *  anything else (older = downgrade, newer = from-the-future misconfig). */
+export declare const USER_TOKEN_VER = 1;
+/** Default cap on `exp - iat`. 15 minutes: long enough for connect + retries, short enough that
+ *  re-mint is the working revocation path. */
+export declare const MAX_TOKEN_TTL_SEC = 900;
+/** The elevated per-connection profiles a bearer may request at exchange time (the "views"):
+ *  read-only god view, space-history purge, channel delete, channel-registry writes, and the
+ *  manifest-deploy preflight. Server-authored into `act.view` ONLY by the human exchange after a
+ *  fresh ledger check against {@link VIEW_REQUIRED_SCOPE}; the callout mints the matching profile
+ *  instead of `agent`. A closed enum on BOTH the mint and validate side — an unknown view fails
+ *  closed, never falls back to a profile. Deliberately NOT a generic `view=<profile>` passthrough:
+ *  most profiles are daemon/provisioning surfaces that must never become human-requestable. */
+export declare const USER_TOKEN_VIEWS: readonly ["admin", "purger", "channel-purger", "channel-writer", "deployer"];
+export type UserTokenView = (typeof USER_TOKEN_VIEWS)[number];
+/** The ONE central view policy table: which ledger capability each view's exchange requires (and
+ *  the callout re-asserts, defense in depth). `admin` = operator authority (god-view read +
+ *  destructive space writes); `deployer` is spawn-grade — deploying YOUR OWN team's manifest rides
+ *  the same owner-domain model as own-agent stop/attach (the manager still enforces owner equality
+ *  at launch, and the view's control grant is the PRIVILEGED tier, never the admin bypass). */
+export declare const VIEW_REQUIRED_SCOPE: Record<UserTokenView, "admin" | "spawn">;
+/** The server-authored actor claim. `owner` restates `sub` (cross-checked); `actor` is the
+ *  ledger-derived agent-instance id; `parent` is at most ONE spawner audit link; `view` is the
+ *  exchange-authorized elevated profile request (absent = the agent profile). */
+export interface UserTokenActor {
+    owner: string;
+    actor: string;
+    scope?: string[];
+    /** The spawning principal (`<owner>.<actor>` dot-form), when this agent was spawned by another. */
+    parent?: string;
+    /** Exchange-authorized elevated view ({@link USER_TOKEN_VIEWS}); absent = agent profile. */
+    view?: UserTokenView;
+}
+/** A fully validated user token, reduced to what the callout needs. */
+export interface ValidatedUserToken {
+    /** The opaque derived owner (== `sub`, format-asserted). */
+    owner: string;
+    /** The space this token is scoped to (== `aud`). */
+    space: string;
+    /** Capability scope (`scope` claim; empty when absent). */
+    scope: string[];
+    /** The validated actor claim. */
+    act: UserTokenActor;
+    /** Token-shape version (== {@link USER_TOKEN_VER}). */
+    ver: number;
+    /** Bearer expiry (unix seconds) — the callout binds the minted NATS user JWT's lifetime to it,
+     *  so broker access dies with the bearer (the v1 revocation lever, enforced server-side). */
+    exp: number;
+}
+export interface ValidateUserTokenOpts {
+    /** The pinned verification key path: a `createRemoteJWKSet(new URL(<pinned origin>))` resolver
+     *  or a local public key. The token itself NEVER influences where the key comes from. */
+    key: JWTVerifyGetKey | CryptoKey;
+    /** Exact expected issuer (the IdP bridge). */
+    issuer: string;
+    /** Exact expected audience — the space name. */
+    audience: string;
+    /** Override of the {@link MAX_TOKEN_TTL_SEC} lifetime cap (tests only; keep short). */
+    maxTtlSec?: number;
+    /** Clock skew tolerance in seconds (default 5). */
+    clockToleranceSec?: number;
+}
+/** Validate a user bearer token. Returns the reduced, validated claims or THROWS — there is no
+ *  partially-valid result and no fallback (a validation failure at the callout is a denied
+ *  connection). */
+export declare function validateUserToken(token: string, opts: ValidateUserTokenOpts): Promise<ValidatedUserToken>;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAGvD;4EAC4E;AAC5E,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;8CAC8C;AAC9C,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;+FAM+F;AAC/F,eAAO,MAAM,gBAAgB,8EAA+E,CAAC;AAC7G,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;+FAI+F;AAC/F,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAMxE,CAAC;AAEF;;iFAEiF;AACjF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,mGAAmG;IACnG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,iCAAiC;IACjC,GAAG,EAAE,cAAc,CAAC;IACpB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ;iGAC6F;IAC7F,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC;6FACyF;IACzF,GAAG,EAAE,eAAe,GAAG,SAAS,CAAC;IACjC,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;mBAEmB;AACnB,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4E/G"}

package/dist/token.js

@@ -0,0 +1,128 @@
+/**
+ * User-token validation — the strict Plane-2 check the auth callout runs on the bearer an agent
+ * presents in `auth_token` (SPEC-normative claim shape; the plan's §"Token shape").
+ *
+ * Claim shape (normative): `sub` = the opaque derived owner · `act` = server-authored
+ * { owner, actor, scope?, parent? } with AT MOST one parent/spawner audit link (nested delegation
+ * chains are cross-account scope, not this plan) · `aud` = the space · `scope` = capability list ·
+ * `ver` = token-shape version (a stale `ver` is rejected — downgrade defense).
+ *
+ * Validation is fail-closed and pinned end-to-end:
+ *  - `alg` pinned to EdDSA (Ed25519) — nothing else verifies;
+ *  - key-smuggling headers (`jku` / `jwk` / `x5u` / `x5c`) are rejected outright — the key is
+ *    resolved ONLY through the caller-pinned resolver (a `createRemoteJWKSet` on a pinned origin,
+ *    or a local key); a `kid` never resolves anywhere else;
+ *  - `iss` / `aud` enforced; `exp`, `iat`, and `nbf` are REQUIRED; the lifetime is capped and
+ *    ANCHORED TO THE VALIDATOR'S CLOCK — future-dated `iat`/`exp` windows are rejected, not just
+ *    long spans (short-lived tokens are the v1 revocation lever — an unbounded or post-dated
+ *    token would quietly disable it).
+ */
+import { decodeProtectedHeader, jwtVerify } from "jose";
+import { assertDerivedOwnerToken, assertValidOwnerToken } from "@cotal-ai/core";
+/** Current normative token-shape version. Bump only with a SPEC change; validators reject
+ *  anything else (older = downgrade, newer = from-the-future misconfig). */
+export const USER_TOKEN_VER = 1;
+/** Default cap on `exp - iat`. 15 minutes: long enough for connect + retries, short enough that
+ *  re-mint is the working revocation path. */
+export const MAX_TOKEN_TTL_SEC = 900;
+/** The elevated per-connection profiles a bearer may request at exchange time (the "views"):
+ *  read-only god view, space-history purge, channel delete, channel-registry writes, and the
+ *  manifest-deploy preflight. Server-authored into `act.view` ONLY by the human exchange after a
+ *  fresh ledger check against {@link VIEW_REQUIRED_SCOPE}; the callout mints the matching profile
+ *  instead of `agent`. A closed enum on BOTH the mint and validate side — an unknown view fails
+ *  closed, never falls back to a profile. Deliberately NOT a generic `view=<profile>` passthrough:
+ *  most profiles are daemon/provisioning surfaces that must never become human-requestable. */
+export const USER_TOKEN_VIEWS = ["admin", "purger", "channel-purger", "channel-writer", "deployer"];
+/** The ONE central view policy table: which ledger capability each view's exchange requires (and
+ *  the callout re-asserts, defense in depth). `admin` = operator authority (god-view read +
+ *  destructive space writes); `deployer` is spawn-grade — deploying YOUR OWN team's manifest rides
+ *  the same owner-domain model as own-agent stop/attach (the manager still enforces owner equality
+ *  at launch, and the view's control grant is the PRIVILEGED tier, never the admin bypass). */
+export const VIEW_REQUIRED_SCOPE = {
+    admin: "admin",
+    purger: "admin",
+    "channel-purger": "admin",
+    "channel-writer": "admin",
+    deployer: "spawn",
+};
+/** Validate a user bearer token. Returns the reduced, validated claims or THROWS — there is no
+ *  partially-valid result and no fallback (a validation failure at the callout is a denied
+ *  connection). */
+export async function validateUserToken(token, opts) {
+    const header = decodeProtectedHeader(token);
+    if (header.jku !== undefined || header.jwk !== undefined || header.x5u !== undefined || header.x5c !== undefined)
+        throw new Error("user token: embedded key material (jku/jwk/x5u/x5c) is rejected - keys resolve only via the pinned JWKS");
+    if (header.alg !== "EdDSA")
+        throw new Error(`user token: alg must be EdDSA (got ${String(header.alg)})`);
+    const { payload } = await jwtVerify(token, opts.key, {
+        algorithms: ["EdDSA"],
+        issuer: opts.issuer,
+        audience: opts.audience,
+        clockTolerance: opts.clockToleranceSec ?? 5,
+    });
+    // jose's `audience` option is SET-MEMBERSHIP (an aud array containing the space passes) — the
+    // bearer must be scoped to EXACTLY this space: the plain string, or a singleton array of it. A
+    // multi-audience bearer would be replayable across spaces.
+    if (payload.aud !== opts.audience && !(Array.isArray(payload.aud) && payload.aud.length === 1 && payload.aud[0] === opts.audience))
+        throw new Error("user token: aud must be exactly the space - a multi-audience bearer is rejected");
+    if (typeof payload.exp !== "number")
+        throw new Error("user token: exp is required (tokens must be short-lived)");
+    if (typeof payload.iat !== "number")
+        throw new Error("user token: iat is required");
+    if (typeof payload.nbf !== "number")
+        throw new Error("user token: nbf is required");
+    // The lifetime cap must hold from the VALIDATOR's clock, not the token's own claims — a signed
+    // token post-dated a year out (iat/exp both in the future) satisfies `exp - iat ≤ cap` and
+    // sails through exp/nbf checks, giving it an effective validity far beyond the cap and quietly
+    // defeating the short-lived-token revocation lever. So: iat may not be in the future, and exp
+    // may not sit further than the cap from now.
+    const maxTtl = opts.maxTtlSec ?? MAX_TOKEN_TTL_SEC;
+    const tol = opts.clockToleranceSec ?? 5;
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.iat > now + tol)
+        throw new Error("user token: iat is in the future");
+    if (payload.exp > now + maxTtl + tol)
+        throw new Error(`user token: exp is more than the ${maxTtl}s cap past now - short-lived tokens are the revocation lever`);
+    if (payload.exp - payload.iat > maxTtl)
+        throw new Error(`user token: lifetime ${payload.exp - payload.iat}s exceeds the ${maxTtl}s cap - short-lived tokens are the revocation lever`);
+    if (payload.ver !== USER_TOKEN_VER)
+        throw new Error(`user token: ver ${String(payload.ver)} != ${USER_TOKEN_VER} - stale or unknown token shape (downgrade defense)`);
+    if (typeof payload.sub !== "string")
+        throw new Error("user token: sub must be a string token - no coercion at a trust boundary");
+    const owner = assertDerivedOwnerToken(payload.sub);
+    const act = payload.act;
+    if (!act || typeof act !== "object")
+        throw new Error("user token: act claim is required (server-authored owner/actor)");
+    if (act.owner !== owner)
+        throw new Error(`user token: act.owner "${String(act.owner)}" != sub "${owner}" - inconsistent principal`);
+    if (typeof act.actor !== "string")
+        throw new Error("user token: act.actor must be a string token - no coercion at a trust boundary");
+    assertValidOwnerToken(act.actor);
+    if (act.scope !== undefined && !(Array.isArray(act.scope) && act.scope.every((s) => typeof s === "string")))
+        throw new Error("user token: act.scope must be a string list when present");
+    if (act.parent !== undefined) {
+        // At most ONE parent audit link, and it must BE a principal (dot-form <owner>.<actor> with a
+        // derived owner) — an arbitrary string here would flow into mint/audit trails unchecked.
+        if (typeof act.parent !== "string")
+            throw new Error("user token: act.parent must be a single principal string when present (no delegation chains)");
+        const parts = act.parent.split(".");
+        if (parts.length !== 2)
+            throw new Error(`user token: act.parent "${act.parent}" is not a principal (<owner>.<actor> dot-form)`);
+        assertDerivedOwnerToken(parts[0]);
+        assertValidOwnerToken(parts[1]);
+    }
+    if (act.view !== undefined && !USER_TOKEN_VIEWS.includes(act.view))
+        throw new Error(`user token: act.view "${String(act.view)}" is not a known view (${USER_TOKEN_VIEWS.join(", ")}) - unknown views fail closed`);
+    const scope = payload.scope === undefined ? [] : payload.scope;
+    if (!(Array.isArray(scope) && scope.every((s) => typeof s === "string")))
+        throw new Error("user token: scope must be a string list when present");
+    return {
+        owner,
+        space: opts.audience,
+        scope,
+        act: { owner: act.owner, actor: act.actor, scope: act.scope, parent: act.parent, view: act.view },
+        ver: USER_TOKEN_VER,
+        exp: payload.exp,
+    };
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,41 @@
 {
   "name": "@cotal-ai/auth",
-  "version": "0.0.0",
-  "description": "Placeholder for @cotal-ai/auth (Cotal per-user authentication). The first real release is published from the Cotal monorepo.",
+  "description": "Cotal per-user auth bridge: opaque owner-token derivation and strict user-token validation for the NATS auth-callout cutover (Plane 1 ↔ Plane 2).",
+  "version": "0.11.0",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/Cotal-AI/Cotal",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Cotal-AI/Cotal.git"
+    "url": "https://github.com/Cotal-AI/Cotal.git",
+    "directory": "implementations/auth"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@nats-io/jwt": "0.0.10-5",
+    "@nats-io/nkeys": "^2.0.3",
+    "@nats-io/transport-node": "^3.4.0",
+    "jose": "^6.2.3",
+    "@cotal-ai/core": "0.11.0",
+    "@cotal-ai/workspace": "0.11.0"
+  },
+  "devDependencies": {
+    "better-auth": "^1.6.23"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.json"
   }
-}
+}

package/README.md

@@ -1,4 +0,0 @@
-# @cotal-ai/auth
-
-Placeholder release to reserve the package name. The real `@cotal-ai/auth` (Cotal per-user
-authentication) is published from the [Cotal monorepo](https://github.com/Cotal-AI/Cotal).