@rayspec/auth-core 1.5.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Socialinsiders UG (haftungsbeschränkt)
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/dist/api-key.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Read the api-key pepper from the environment. THROWS if missing/blank — the boot-required
+ * contract (the pepper is in the boot-fails-closed set alongside the JWT signing key).
+ */
+export declare function getApiKeyPepper(): string;
+/** HMAC-SHA256 the secret with the boot-required pepper; returns a lowercase hex digest. */
+export declare function hashApiKey(secret: string, pepper?: string): string;
+/**
+ * Constant-time verify of a presented secret against a stored HMAC hash. Recomputes the HMAC
+ * under the pepper and compares with timingSafeEqual (length-guarded so a wrong-length hash
+ * does not throw). Never branches observably on the hash contents.
+ */
+export declare function verifyApiKey(storedHash: string, secret: string, pepper?: string): boolean;
+export interface MintedApiKey {
+    /** The full plaintext shown to the user ONCE: `${prefix}.${secret}`. Never stored. */
+    plaintext: string;
+    /** The public, indexed lookup handle (safe to store + query). */
+    prefix: string;
+    /** The HMAC hash to persist (key_hash). */
+    hash: string;
+}
+/**
+ * Mint a new api-key: a short public prefix + a ≥128-bit secret. Returns the one-time
+ * plaintext, the prefix to index, and the HMAC hash to store. The secret is 32 bytes
+ * (256-bit) of CSPRNG, base64url-encoded.
+ */
+export declare function mintApiKey(pepper?: string): MintedApiKey;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAQxC;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAA0B,GAAG,MAAM,CAErF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAA0B,GACjC,OAAO,CAMT;AAED,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAE,MAA0B,GAAG,YAAY,CAK3E"}

package/dist/api-key.js

@@ -0,0 +1,56 @@
+/**
+ * API-key / client-secret hashing primitive — HMAC-SHA256 with a server PEPPER (a deliberate
+ * choice: fast on the hot per-request auth path, sound for ≥128-bit machine secrets;
+ * argon2id is reserved for low-entropy passwords). Uses node:crypto (stdlib) only.
+ *
+ * The pepper is REQUIRED-AT-BOOT: `getApiKeyPepper()` throws if RAYSPEC_API_KEY_PEPPER is
+ * unset/blank, so a misconfigured deploy fails closed instead of silently hashing keys with
+ * an empty pepper. (RAYSPEC_API_KEY_PEPPER is wired into ci.yml + the boot-fails-closed
+ * test; here the primitive is the boot-required seam.)
+ *
+ * Storage model: plaintext shown ONCE at mint; only the public `keyPrefix` (indexed for O(1)
+ * lookup) + the HMAC `keyHash` are persisted. Verification recomputes the HMAC and compares
+ * in constant time (timingSafeEqual) so a stored-hash comparison cannot be timed.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+const PEPPER_ENV = 'RAYSPEC_API_KEY_PEPPER';
+/**
+ * Read the api-key pepper from the environment. THROWS if missing/blank — the boot-required
+ * contract (the pepper is in the boot-fails-closed set alongside the JWT signing key).
+ */
+export function getApiKeyPepper() {
+    const pepper = process.env[PEPPER_ENV];
+    if (!pepper || pepper.trim().length === 0) {
+        throw new Error(`${PEPPER_ENV} is required at boot (the api-key HMAC pepper). Refusing to start without it.`);
+    }
+    return pepper;
+}
+/** HMAC-SHA256 the secret with the boot-required pepper; returns a lowercase hex digest. */
+export function hashApiKey(secret, pepper = getApiKeyPepper()) {
+    return createHmac('sha256', pepper).update(secret).digest('hex');
+}
+/**
+ * Constant-time verify of a presented secret against a stored HMAC hash. Recomputes the HMAC
+ * under the pepper and compares with timingSafeEqual (length-guarded so a wrong-length hash
+ * does not throw). Never branches observably on the hash contents.
+ */
+export function verifyApiKey(storedHash, secret, pepper = getApiKeyPepper()) {
+    const computed = hashApiKey(secret, pepper);
+    const a = Buffer.from(computed, 'utf8');
+    const b = Buffer.from(storedHash, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * Mint a new api-key: a short public prefix + a ≥128-bit secret. Returns the one-time
+ * plaintext, the prefix to index, and the HMAC hash to store. The secret is 32 bytes
+ * (256-bit) of CSPRNG, base64url-encoded.
+ */
+export function mintApiKey(pepper = getApiKeyPepper()) {
+    const prefix = `rk_${randomBytes(6).toString('base64url')}`;
+    const secret = randomBytes(32).toString('base64url'); // 256-bit
+    const plaintext = `${prefix}.${secret}`;
+    return { plaintext, prefix, hash: hashApiKey(secret, pepper) };
+}
+//# sourceMappingURL=api-key.js.map

package/dist/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,UAAU,GAAG,wBAAwB,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,+EAA+E,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,SAAiB,eAAe,EAAE;IAC3E,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,MAAc,EACd,SAAiB,eAAe,EAAE;IAElC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,SAAiB,eAAe,EAAE;IAC3D,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;IAC5D,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU;IAChE,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;IACxC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;AACjE,CAAC"}

package/dist/audit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Neutral auth-audit EVENT shape (the DB write is api-auth's audit-store).
+ *
+ * Services return a list of AuditEvents describing what happened; the route layer commits them
+ * OUT-OF-BAND (their own unit of work) so a 404/rollback of the main request never drops a
+ * security event. Cross-tenant-denial events record the ACTOR's resolved tenant
+ * authoritatively + the attempted target as an opaque `targetHash` (never a target-org FK the
+ * actor does not own). Hashes/metadata only — no raw secrets/PII.
+ */
+/** The closed set of audited auth events. */
+export type AuthEventName = 'register' | 'login' | 'login_failed' | 'refresh' | 'refresh_reuse_detected' | 'logout' | 'org_create' | 'org_switch' | 'org_member_add' | 'org_member_change' | 'org_invite_issued' | 'apikey_mint' | 'apikey_revoke' | 'apikey_auth_failed' | 'cross_tenant_denied' | 'authz_denied';
+/** One audit event a service emits for the route to commit out-of-band. */
+export interface AuditEvent {
+    event: AuthEventName;
+    /** The actor's resolved tenant (authoritative; null when pre-org). */
+    actorOrgId?: string | null;
+    /** The actor's user id (null for fully anonymous failures). */
+    actorUserId?: string | null;
+    /** Refresh family id, when relevant. */
+    familyId?: string | null;
+    /** Opaque hash of an attempted cross-tenant target (NEVER a target-org FK). */
+    targetHash?: string | null;
+    /** Extra non-PII metadata (hashes/flags only). */
+    meta?: Record<string, unknown>;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,OAAO,GACP,cAAc,GACd,SAAS,GACT,wBAAwB,GACxB,QAAQ,GACR,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,oBAAoB,GACpB,qBAAqB,GACrB,cAAc,CAAC;AAEnB,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,aAAa,CAAC;IACrB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC"}

package/dist/audit.js

@@ -0,0 +1,11 @@
+/**
+ * Neutral auth-audit EVENT shape (the DB write is api-auth's audit-store).
+ *
+ * Services return a list of AuditEvents describing what happened; the route layer commits them
+ * OUT-OF-BAND (their own unit of work) so a 404/rollback of the main request never drops a
+ * security event. Cross-tenant-denial events record the ACTOR's resolved tenant
+ * authoritatively + the attempted target as an opaque `targetHash` (never a target-org FK the
+ * actor does not own). Hashes/metadata only — no raw secrets/PII.
+ */
+export {};
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/authz.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Authorization — the static ROLE_PERMISSIONS table + the authorize() contract.
+ * DB-free here; the LIVE membership lookup is injected by the caller (api-auth holds the
+ * IdentityStore). A general policy engine is overkill here — a static code constant.
+ *
+ * THE CRITICAL SPLIT: for SENSITIVE/MUTATING permissions the caller MUST resolve the role from a
+ * LIVE membership lookup (TenantDb/IdentityStore), NOT the JWT claim — so a revoked/demoted
+ * principal is denied within the ~8-min token TTL (the TTL is a bounded READ-staleness risk, not
+ * a write-privilege bypass). `isSensitive(permission)` tells the caller which path to take.
+ */
+/**
+ * The closed set of permissions.
+ *
+ * `store:read`/`store:write` are the GENERIC, product-agnostic CRUD permissions a
+ * declared `api` route over a materialized store is gated by — read ops (list/get) require
+ * `store:read`, mutating ops (create/update/delete) require `store:write`. They are NOT
+ * store-specific (no `notebooks:*`): the platform stays product-free and one pair gates every
+ * declared store route. `store:write` is SENSITIVE (a live-membership recheck on every mutation,
+ * mirroring why a write must never trust a stale JWT claim — see the SENSITIVE set below).
+ */
+export type Permission = 'agent:run' | 'agent:read' | 'store:read' | 'store:write' | 'org:read' | 'org:member:add' | 'org:member:change' | 'org:switch' | 'apikey:read' | 'apikey:mint' | 'apikey:revoke';
+/** Roles → the permissions they grant (static; owner ⊇ admin ⊇ member). */
+export declare const ROLE_PERMISSIONS: Record<string, Permission[]>;
+/** True if `permission` requires a live membership check (never trust the JWT claim). */
+export declare function isSensitive(permission: Permission): boolean;
+/**
+ * The CLOSED set of permissions an api-key principal may EVER exercise — its scopes ∩ this set. This
+ * is the SINGLE source of truth for both `authorize()` (the runtime gate) and the `ApiKeyScope` DTO
+ * enum (the mint-time grammar; dto.ts derives its enum from this so the two can never silently
+ * desync). It is purely scope-driven (an api-key is a machine principal with NO membership/role).
+ *
+ * What is DELIBERATELY ABSENT is the security boundary: the org-MANAGEMENT sensitive ops
+ * (`apikey:mint`, `apikey:revoke`, `org:member:change`, `org:switch`) are NOT here, so an api-key can
+ * never perform them regardless of scope. `store:write` IS here (the programmatic/agency consumer
+ * model — a desktop app / automation POSTing rows authenticates via an org-scoped key); it is also
+ * SENSITIVE, but for an api-key the KEY is the live credential, so requirePermission falls api-keys
+ * through to authorize(), where this set ∩ scopes is the gate (no stale-claim recheck applies).
+ *
+ * Frozen so a caller cannot mutate the shared authority; `authorize()` reads it via `.includes`.
+ */
+export declare const API_KEY_GRANTABLE: readonly Permission[];
+/** Does `role` grant `permission` per the static table? */
+export declare function roleGrants(role: string | undefined, permission: Permission): boolean;
+/**
+ * The principal an authorize() call evaluates. For sensitive permissions the caller supplies the
+ * LIVE role (resolved via the membership store); for read-mostly permissions the JWT-claim role
+ * is acceptable.
+ */
+export interface AuthzPrincipal {
+    userId?: string;
+    /** The role to evaluate against — LIVE for sensitive ops, claim-derived otherwise. */
+    role?: string;
+    /** API-key scopes (an api-key principal is also gated by its granted scopes). */
+    scopes?: string[];
+}
+/**
+ * Decide whether `principal` may perform `permission` in the (already tenant-resolved) org.
+ *
+ * Pure decision: the caller has ALREADY (a) asserted the principal belongs to the tenant and
+ * (b) for a sensitive permission, set `principal.role` from a LIVE membership lookup. For an
+ * api-key principal, the permission must ALSO be within its granted scopes (scope ∩ role).
+ */
+export declare function authorize(principal: AuthzPrincipal, permission: Permission, opts?: {
+    isApiKey?: boolean;
+}): boolean;
+//# sourceMappingURL=authz.d.ts.map

package/dist/authz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz.d.ts","sourceRoot":"","sources":["../src/authz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,UAAU,GACV,gBAAgB,GAChB,mBAAmB,GACnB,YAAY,GACZ,aAAa,GACb,aAAa,GACb,eAAe,CAAC;AAEpB,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CA0BzD,CAAC;AAmBF,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,UAAU,EAOjD,CAAC;AAEH,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAGpF;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,UAAU,EACtB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAeT"}

package/dist/authz.js

@@ -0,0 +1,112 @@
+/**
+ * Authorization — the static ROLE_PERMISSIONS table + the authorize() contract.
+ * DB-free here; the LIVE membership lookup is injected by the caller (api-auth holds the
+ * IdentityStore). A general policy engine is overkill here — a static code constant.
+ *
+ * THE CRITICAL SPLIT: for SENSITIVE/MUTATING permissions the caller MUST resolve the role from a
+ * LIVE membership lookup (TenantDb/IdentityStore), NOT the JWT claim — so a revoked/demoted
+ * principal is denied within the ~8-min token TTL (the TTL is a bounded READ-staleness risk, not
+ * a write-privilege bypass). `isSensitive(permission)` tells the caller which path to take.
+ */
+/** Roles → the permissions they grant (static; owner ⊇ admin ⊇ member). */
+export const ROLE_PERMISSIONS = {
+    owner: [
+        'agent:run',
+        'agent:read',
+        'store:read',
+        'store:write',
+        'org:read',
+        'org:member:add',
+        'org:member:change',
+        'org:switch',
+        'apikey:read',
+        'apikey:mint',
+        'apikey:revoke',
+    ],
+    admin: [
+        'agent:run',
+        'agent:read',
+        'store:read',
+        'store:write',
+        'org:read',
+        'org:switch',
+        'apikey:read',
+        'apikey:mint',
+        'apikey:revoke',
+    ],
+    member: ['agent:run', 'agent:read', 'store:read', 'store:write', 'org:read', 'org:switch'],
+};
+/**
+ * SENSITIVE/MUTATING permissions — for these the caller MUST do a LIVE membership+role lookup and
+ * MUST NOT trust the JWT claim. (org switch is included: it re-mints a privileged token, so it
+ * re-checks live.)
+ */
+const SENSITIVE = new Set([
+    'apikey:mint',
+    'apikey:revoke',
+    'org:member:add',
+    'org:member:change',
+    'org:switch',
+    // A declared-store MUTATION (create/update/delete) must re-check live membership — a revoked/
+    // demoted principal must not write product data on a stale JWT claim (the same write-bypass
+    // reasoning that makes the api-key/org-management ops sensitive). store:read stays claim-trusted.
+    'store:write',
+]);
+/** True if `permission` requires a live membership check (never trust the JWT claim). */
+export function isSensitive(permission) {
+    return SENSITIVE.has(permission);
+}
+/**
+ * The CLOSED set of permissions an api-key principal may EVER exercise — its scopes ∩ this set. This
+ * is the SINGLE source of truth for both `authorize()` (the runtime gate) and the `ApiKeyScope` DTO
+ * enum (the mint-time grammar; dto.ts derives its enum from this so the two can never silently
+ * desync). It is purely scope-driven (an api-key is a machine principal with NO membership/role).
+ *
+ * What is DELIBERATELY ABSENT is the security boundary: the org-MANAGEMENT sensitive ops
+ * (`apikey:mint`, `apikey:revoke`, `org:member:change`, `org:switch`) are NOT here, so an api-key can
+ * never perform them regardless of scope. `store:write` IS here (the programmatic/agency consumer
+ * model — a desktop app / automation POSTing rows authenticates via an org-scoped key); it is also
+ * SENSITIVE, but for an api-key the KEY is the live credential, so requirePermission falls api-keys
+ * through to authorize(), where this set ∩ scopes is the gate (no stale-claim recheck applies).
+ *
+ * Frozen so a caller cannot mutate the shared authority; `authorize()` reads it via `.includes`.
+ */
+export const API_KEY_GRANTABLE = Object.freeze([
+    'agent:run',
+    'agent:read',
+    'store:read',
+    'store:write',
+    'org:read',
+    'apikey:read',
+]);
+/** Does `role` grant `permission` per the static table? */
+export function roleGrants(role, permission) {
+    if (!role)
+        return false;
+    return (ROLE_PERMISSIONS[role] ?? []).includes(permission);
+}
+/**
+ * Decide whether `principal` may perform `permission` in the (already tenant-resolved) org.
+ *
+ * Pure decision: the caller has ALREADY (a) asserted the principal belongs to the tenant and
+ * (b) for a sensitive permission, set `principal.role` from a LIVE membership lookup. For an
+ * api-key principal, the permission must ALSO be within its granted scopes (scope ∩ role).
+ */
+export function authorize(principal, permission, opts = {}) {
+    // The permissions an api-key may EVER exercise — purely its scopes, NO role (an api-key is a
+    // machine principal with no membership). Sensitive org-management ops are NOT in this set, so
+    // an api-key can never mint/revoke keys or change membership/switch org regardless of scope.
+    if (opts.isApiKey) {
+        // The api-key-grantable SET is the single shared authority (API_KEY_GRANTABLE above): an api-key
+        // may exercise ONLY a permission that is BOTH in that set AND in its scopes. The org-MANAGEMENT
+        // sensitive ops (apikey:mint/revoke, org:member:change, org:switch) are absent from the set, so
+        // an api-key can never perform them regardless of scope. (store:write IS in the set — the
+        // programmatic/agency consumer model — see API_KEY_GRANTABLE's rationale.)
+        if (!API_KEY_GRANTABLE.includes(permission))
+            return false;
+        return (principal.scopes ?? []).includes(permission);
+    }
+    // User principals: the role (LIVE for sensitive ops, claim-derived otherwise) must grant it.
+    return roleGrants(principal.role, permission);
+}
+//# sourceMappingURL=authz.js.map

package/dist/authz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz.js","sourceRoot":"","sources":["../src/authz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyBH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAiC;IAC5D,KAAK,EAAE;QACL,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,aAAa;QACb,UAAU;QACV,gBAAgB;QAChB,mBAAmB;QACnB,YAAY;QACZ,aAAa;QACb,aAAa;QACb,eAAe;KAChB;IACD,KAAK,EAAE;QACL,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,aAAa;QACb,UAAU;QACV,YAAY;QACZ,aAAa;QACb,aAAa;QACb,eAAe;KAChB;IACD,MAAM,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,CAAC;CAC3F,CAAC;AAEF;;;;GAIG;AACH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAa;IACpC,aAAa;IACb,eAAe;IACf,gBAAgB;IAChB,mBAAmB;IACnB,YAAY;IACZ,8FAA8F;IAC9F,4FAA4F;IAC5F,kGAAkG;IAClG,aAAa;CACd,CAAC,CAAC;AAEH,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,UAAsB;IAChD,OAAO,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA0B,MAAM,CAAC,MAAM,CAAC;IACpE,WAAW;IACX,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,UAAU;IACV,aAAa;CACd,CAAC,CAAC;AAEH,2DAA2D;AAC3D,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,UAAsB;IACzE,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC7D,CAAC;AAeD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,SAAyB,EACzB,UAAsB,EACtB,OAA+B,EAAE;IAEjC,6FAA6F;IAC7F,8FAA8F;IAC9F,6FAA6F;IAC7F,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,iGAAiG;QACjG,gGAAgG;QAChG,gGAAgG;QAChG,0FAA0F;QAC1F,2EAA2E;QAC3E,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1D,OAAO,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACvD,CAAC;IACD,6FAA6F;IAC7F,OAAO,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Boot-required secret configuration (no plaintext secrets, fail-closed at boot).
+ *
+ * Two secrets are REQUIRED-AT-BOOT and live ONLY in env/secret-manager, never in the DB or git:
+ *   - RAYSPEC_JWT_SIGNING_KEY — the PKCS#8 PEM private key the access-token signer uses.
+ *   - RAYSPEC_API_KEY_PEPPER  — the HMAC pepper for api-key/client-secret hashing (api-key.ts).
+ *
+ * `assertBootSecrets()` throws if either is missing/blank, so a misconfigured deploy fails to
+ * start rather than silently minting unsignable tokens or hashing keys with an empty pepper. The
+ * api-auth app calls it at construction; the boot-fails-closed test asserts it throws when a
+ * secret is absent.
+ */
+export declare const JWT_SIGNING_KEY_ENV = "RAYSPEC_JWT_SIGNING_KEY";
+export declare const API_KEY_PEPPER_ENV = "RAYSPEC_API_KEY_PEPPER";
+/** Read the JWT signing key PEM; THROWS if unset/blank (boot-required). */
+export declare function getJwtSigningKeyPem(): string;
+/**
+ * Assert BOTH boot-required secrets are present. Throws a single combined error listing every
+ * missing one. Call this once at app construction (fail-closed boot). Does NOT validate the key
+ * material itself — the token module does that lazily on first sign (which also fails closed).
+ */
+export declare function assertBootSecrets(env?: NodeJS.ProcessEnv): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAC7D,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAE3D,2EAA2E;AAC3E,wBAAgB,mBAAmB,IAAI,MAAM,CAS5C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAc5E"}

package/dist/config.js

@@ -0,0 +1,42 @@
+/**
+ * Boot-required secret configuration (no plaintext secrets, fail-closed at boot).
+ *
+ * Two secrets are REQUIRED-AT-BOOT and live ONLY in env/secret-manager, never in the DB or git:
+ *   - RAYSPEC_JWT_SIGNING_KEY — the PKCS#8 PEM private key the access-token signer uses.
+ *   - RAYSPEC_API_KEY_PEPPER  — the HMAC pepper for api-key/client-secret hashing (api-key.ts).
+ *
+ * `assertBootSecrets()` throws if either is missing/blank, so a misconfigured deploy fails to
+ * start rather than silently minting unsignable tokens or hashing keys with an empty pepper. The
+ * api-auth app calls it at construction; the boot-fails-closed test asserts it throws when a
+ * secret is absent.
+ */
+export const JWT_SIGNING_KEY_ENV = 'RAYSPEC_JWT_SIGNING_KEY';
+export const API_KEY_PEPPER_ENV = 'RAYSPEC_API_KEY_PEPPER';
+/** Read the JWT signing key PEM; THROWS if unset/blank (boot-required). */
+export function getJwtSigningKeyPem() {
+    const pem = process.env[JWT_SIGNING_KEY_ENV];
+    if (!pem || pem.trim().length === 0) {
+        throw new Error(`${JWT_SIGNING_KEY_ENV} is required at boot (the JWT signing key, PKCS#8 PEM). ` +
+            'Refusing to start without it.');
+    }
+    return pem;
+}
+/**
+ * Assert BOTH boot-required secrets are present. Throws a single combined error listing every
+ * missing one. Call this once at app construction (fail-closed boot). Does NOT validate the key
+ * material itself — the token module does that lazily on first sign (which also fails closed).
+ */
+export function assertBootSecrets(env = process.env) {
+    const missing = [];
+    if (!env[JWT_SIGNING_KEY_ENV] || env[JWT_SIGNING_KEY_ENV]?.trim().length === 0) {
+        missing.push(JWT_SIGNING_KEY_ENV);
+    }
+    if (!env[API_KEY_PEPPER_ENV] || env[API_KEY_PEPPER_ENV]?.trim().length === 0) {
+        missing.push(API_KEY_PEPPER_ENV);
+    }
+    if (missing.length > 0) {
+        throw new Error(`Boot-required secret(s) missing: ${missing.join(', ')}. ` +
+            'These live in env/secret-manager only (never DB/git). Refusing to start (fail-closed).');
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,yBAAyB,CAAC;AAC7D,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,GAAG,mBAAmB,0DAA0D;YAC9E,+BAA+B,CAClC,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACpE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,GAAG,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/E,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,GAAG,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7E,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,oCAAoC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACxD,wFAAwF,CAC3F,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/deferrals.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The before-external-exposure deferral line — EXPLICIT, in code, so the boundary is auditable.
+ *
+ * The following are NOT shipped yet (they are gated to BEFORE external/SaaS exposure). The
+ * platform deliberately ships the forward-compatible HOOKS for each so enabling them is a
+ * config/policy change, not a re-architecture:
+ *
+ *   - KMS per-tenant DEK + crypto-shred         → hook: orgs.region + ON DELETE CASCADE purge of
+ *                                                  the at-rest raw-PII columns: the jsonb
+ *                                                  payloads conversation_items.payload, runs.output,
+ *                                                  journal_steps.output, run_events.data + the text
+ *                                                  runs.final_text. (NOT conversation_items.content
+ *                                                  — deprecated legacy column, part data now lives in
+ *                                                  payload; see schema.ts.)
+ *   - Postgres Row-Level Security (RLS)          → hook: the TenantDb.transaction() set_config
+ *                                                  app.current_tenant GUC seam (TENANT_GUC) — RLS
+ *                                                  policies bind to an already-populated GUC with
+ *                                                  zero call-site churn.
+ *   - DPoP-bound access tokens                   → hook: the jose access-token module (add a cnf
+ *                                                  claim + DPoP proof verification).
+ *   - Per-tenant tool/handler sandbox            → hook: the neutral Backend boundary + per-tenant
+ *                                                  CLAUDE_CONFIG_DIR isolation already in the
+ *                                                  Anthropic adapter.
+ *   - jti denylist (immediate token revocation)  → hook: the jti claim is minted on every token;
+ *                                                  the opaque session is the revocation point
+ *                                                  (the ~8-min TTL bounds stateless-read staleness).
+ *
+ * This constant is exported so a grep for `SECURITY_DEFERRALS_10B` finds the single source of the
+ * deferral record; it is referenced by the docs and intentionally never used as runtime logic.
+ */
+export declare const SECURITY_DEFERRALS_10B: readonly ["kms-per-tenant-dek-crypto-shred", "postgres-row-level-security", "dpop-bound-tokens", "per-tenant-tool-sandbox", "jti-denylist"];
+export type SecurityDeferral10B = (typeof SECURITY_DEFERRALS_10B)[number];
+//# sourceMappingURL=deferrals.d.ts.map

package/dist/deferrals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferrals.d.ts","sourceRoot":"","sources":["../src/deferrals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,sBAAsB,6IAMzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/deferrals.js

@@ -0,0 +1,38 @@
+/**
+ * The before-external-exposure deferral line — EXPLICIT, in code, so the boundary is auditable.
+ *
+ * The following are NOT shipped yet (they are gated to BEFORE external/SaaS exposure). The
+ * platform deliberately ships the forward-compatible HOOKS for each so enabling them is a
+ * config/policy change, not a re-architecture:
+ *
+ *   - KMS per-tenant DEK + crypto-shred         → hook: orgs.region + ON DELETE CASCADE purge of
+ *                                                  the at-rest raw-PII columns: the jsonb
+ *                                                  payloads conversation_items.payload, runs.output,
+ *                                                  journal_steps.output, run_events.data + the text
+ *                                                  runs.final_text. (NOT conversation_items.content
+ *                                                  — deprecated legacy column, part data now lives in
+ *                                                  payload; see schema.ts.)
+ *   - Postgres Row-Level Security (RLS)          → hook: the TenantDb.transaction() set_config
+ *                                                  app.current_tenant GUC seam (TENANT_GUC) — RLS
+ *                                                  policies bind to an already-populated GUC with
+ *                                                  zero call-site churn.
+ *   - DPoP-bound access tokens                   → hook: the jose access-token module (add a cnf
+ *                                                  claim + DPoP proof verification).
+ *   - Per-tenant tool/handler sandbox            → hook: the neutral Backend boundary + per-tenant
+ *                                                  CLAUDE_CONFIG_DIR isolation already in the
+ *                                                  Anthropic adapter.
+ *   - jti denylist (immediate token revocation)  → hook: the jti claim is minted on every token;
+ *                                                  the opaque session is the revocation point
+ *                                                  (the ~8-min TTL bounds stateless-read staleness).
+ *
+ * This constant is exported so a grep for `SECURITY_DEFERRALS_10B` finds the single source of the
+ * deferral record; it is referenced by the docs and intentionally never used as runtime logic.
+ */
+export const SECURITY_DEFERRALS_10B = [
+    'kms-per-tenant-dek-crypto-shred',
+    'postgres-row-level-security',
+    'dpop-bound-tokens',
+    'per-tenant-tool-sandbox',
+    'jti-denylist',
+];
+//# sourceMappingURL=deferrals.js.map

package/dist/deferrals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferrals.js","sourceRoot":"","sources":["../src/deferrals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,iCAAiC;IACjC,6BAA6B;IAC7B,mBAAmB;IACnB,yBAAyB;IACzB,cAAc;CACN,CAAC"}