@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/api-keys.js

@@ -0,0 +1,298 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * 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.
+ */ /**
+ * Customer API keys (AGL-616). Keys authenticate the public REST API
+ * (`/api/v1/**`). Only a SHA-256 hash of the key is ever stored — the raw
+ * token is shown to the user exactly once, at creation. The Firestore doc id
+ * IS the hash, so verification is an O(1) `get()` and the hash never leaves
+ * the server (listings return metadata only). The `apiKeys` collection is
+ * deny-all in the security rules; all access is Admin-SDK only.
+ *
+ * The token/hash/format/scope helpers are pure and unit-tested; the storage
+ * functions wrap the Admin SDK.
+ */ import { createHash, randomBytes } from "node:crypto";
+import { firebaseAdmin } from "./firebase-admin.js";
+/**
+ * Scopes a key can be granted, as `resource:action`. Every entry must be
+ * enforced by a real endpoint — a mintable scope that grants nothing reads
+ * as a broken permission (AGL-899 removed `contacts:write` on those grounds,
+ * and AGL-2276 re-added it in the same change that shipped the writes, which
+ * is the condition AGL-899 set).
+ */ export const API_SCOPES = [
+    'datasets:read',
+    'datasets:write',
+    'contacts:read',
+    // AGL-2276. Contacts used to arrive only through the four site capture
+    // points, so an integration that OWNS the customer list upstream — a CRM,
+    // a mailing tool, a migration off another platform — could read the
+    // audience and never add to it. The write is metered against the same
+    // audience bands capture is (AGL-890): `checkContactQuota` on the create,
+    // and the monthly rollup counts `orgs/{orgId}/contacts` whatever wrote
+    // them, so an API-created contact bills exactly like a form-captured one.
+    // The scope covers the create, the tag/notes edit the console's Contacts
+    // page already makes, and the delete — never `email`, which is the dedupe
+    // key, and never `sources`/`interactions`, which are provenance.
+    'contacts:write',
+    'sites:read',
+    // AGL-2462. An integration could write a dataset record over /v1 and had no
+    // way to make a live page show it: `getDatasets` caches for 60s behind
+    // `tenant-data:{hostId}` and the catch-all page is `revalidate = 60`, and
+    // time-based ISR is stale-while-revalidate — so the visitor AFTER the window
+    // can still get the old copy. A cache expiring is not a publish.
+    //
+    // Its OWN scope rather than a `sites:write` covering two very different
+    // powers. Publishing is not a site edit: it changes no stored field, and it
+    // is the one /v1 call whose cost lands on a different service — up to 250
+    // dropped pages, each re-rendering at roughly 40 Firestore reads. A key that
+    // syncs a catalogue should not thereby be able to spend that, and an
+    // integration that only needs to flush its own writes should not have to
+    // hold a scope that could rename the site. Bounded by a per-HOST hourly
+    // budget on top of the per-key request limit, because one call and 250
+    // dropped pages are not the same unit of cost.
+    'sites:publish',
+    // AGL-2465. Everything downstream of a site was automatable and creating
+    // the site was not: `handleSites` 405'd every non-GET, so an agency
+    // onboarding a client could push its datasets, contacts and media and still
+    // had to open a browser to make the site those things go in.
+    //
+    // CREATE ONLY — no rename, no delete, and the omissions are deliberate
+    // rather than unfinished. `hosts/rename` authorizes off the host projection
+    // alone — the member's own entry in `memberRoles`, which must equal
+    // `admin` — and an API key is an ORG credential with no uid, so that gate
+    // has no translation at all; giving it one is a permission decision, not a
+    // port. `hosts/delete` runs
+    // `recursiveDelete` over the whole site plus a storage prefix wipe with no
+    // hold and no soft-delete, and the type-the-name confirmation that guards it
+    // is console UI only — a one-field irreversible delete is the last thing to
+    // put behind a bearer token, and whether it should exist at all is a product
+    // decision that has not been made.
+    //
+    // Replay-safe, which is what actually blocked this: site creation is the
+    // most expensive object here to duplicate — it takes a `hostLimit` slot,
+    // writes `hostIndex` and runs `syncOrgAuthProjections` across every member —
+    // and `/v1` publishes idempotency as a contract. A POST that succeeded
+    // server-side but lost its response now replays the original site rather
+    // than minting a second one.
+    'sites:write',
+    'forms:read',
+    // AGL-2127. A lead sync could READ a submission and never record that it
+    // had — so it re-pushed the same lead on every poll, or kept its own
+    // high-water mark against a list ordered by document id rather than by
+    // time. `read` is the flag the console already toggles on the same
+    // document, so the scope grants exactly the state the integration needs
+    // (plus the delete that lets it purge after export), and nothing that
+    // rewrites what a visitor actually typed.
+    'forms:write',
+    // Commerce and media reads (AGL-1928). Each is separate from `sites:read`
+    // for the same reason `forms:read` is: a key handed to a fulfilment or
+    // accounting integration needs the order history and nothing else, and a
+    // key that syncs a catalogue into a PIM should not thereby be able to read
+    // every form submission a site has ever taken. Read-only on purpose —
+    // writes here move money or stock and want their own decision, in the same
+    // change that ships them (the AGL-899 rule for `contacts:write`).
+    'orders:read',
+    // AGL-2461. The read-only note above says commerce writes wait for "their
+    // own decision, in the same change that ships them" because they "move
+    // money or stock". Recording a shipment does NEITHER — `fulfill-order.ts`'s
+    // own header says so: "a forward status flip plus a timeline entry, no
+    // stock moved, no money moved" — so it is precisely the write that rule
+    // admits, and it is the day-one commerce automation: a 3PL, ShipStation, or
+    // a warehouse's own system marking an order shipped with a tracking number.
+    // A public API that can take an order and never ship it is a fulfilment
+    // dead end.
+    //
+    // Fulfilment ONLY. `cancelled` and `refunded` are refused by name with a
+    // 400: those move stock and money through their own transactions, and this
+    // scope must never become the door around them. The transition rule itself
+    // is not re-implemented here at all — the write goes through the commerce
+    // plugin's own transaction via the order-fulfilment capability registry,
+    // so the API can never write a status the console forbids.
+    'orders:write',
+    'products:read',
+    'media:read',
+    // AGL-2463. `media:read` was the only media scope, so an agency onboarding a
+    // client site could automate everything about that site except putting its
+    // images in it — an integration could LIST the library and never add to it,
+    // which stops the asset pipeline at the one step that matters.
+    //
+    // Create only: no replace, no delete, no edit of an existing file's metadata.
+    // A key handed to a migration tool should be able to fill a library and not
+    // to empty one, and the destructive half wants its own decision in the change
+    // that ships it — the same rule that kept this scope out until now.
+    //
+    // Charged, not free: the create goes through `mediaStorageGate`, the same
+    // helper the console's four ingress routes use, and consumes the existing
+    // per-GB storage dimension rather than inventing a per-upload one.
+    'media:write',
+    // AGL-2606. The CRM v2 collections (AGL-2595) — companies, pipelines,
+    // deals, tasks and activities — sit beside `contacts` and were reachable
+    // only from the console, so the integration that owns the sales process
+    // upstream (a CRM sync, a dialer logging calls, a billing system closing
+    // deals) could read the people and nothing they were doing with them.
+    //
+    // ONE pair for the five resources rather than five, because a key that
+    // needs any of them needs the set: a deal names a company and a contact, a
+    // task names a deal, an activity names all three, and a key that could
+    // read deals but not the pipelines whose stages they cite would hand back
+    // stage ids it cannot explain. The contact's own CRM profile — phone, job
+    // title, company, owner, lifecycle stage — stays under `contacts:*`, since
+    // it is a field of the contact and reads with the contact.
+    //
+    // Reads are org-wide, as every read on this surface is: a key is an
+    // organization credential. Writes name the site they belong to and are
+    // stamped in that site's scope (`crmCreateStamp`), so an API-created deal
+    // lands exactly where a console-created one would, and never wider.
+    'crm:read',
+    'crm:write'
+];
+/** Live-key token prefix. A `_test_` variant can follow the same shape later. */ export const API_KEY_TOKEN_PREFIX = 'aglyn_sk_';
+/** Top-level collection; doc id = the token hash. */ export const API_KEYS_COLLECTION = 'apiKeys';
+/** How much of the raw token is retained (plaintext) for display/identification. */ const DISPLAY_BODY_CHARS = 6;
+// ── Pure helpers (unit-tested; no I/O) ──────────────────────────────────────
+/** True if `value` is one of the known scopes. */ export function isApiScope(value) {
+    return API_SCOPES.includes(value);
+}
+/** Keep only valid, de-duplicated scopes, preserving `API_SCOPES` order. */ export function normalizeScopes(scopes) {
+    const set = new Set(scopes.filter(isApiScope));
+    return API_SCOPES.filter((scope)=>set.has(scope));
+}
+/** SHA-256 hex of a raw token — the Firestore doc id and lookup key. */ export function hashApiKey(token) {
+    return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+/** Structural check before hashing/looking up — cheap reject of junk input. */ export function isValidApiKeyFormat(token) {
+    return typeof token === 'string' && token.startsWith(API_KEY_TOKEN_PREFIX) && /^[A-Za-z0-9_-]{24,}$/.test(token.slice(API_KEY_TOKEN_PREFIX.length));
+}
+/**
+ * Generate a fresh token plus the derived hash and display prefix. The raw
+ * `token` is the only time the secret exists in plaintext — persist the hash,
+ * hand the token to the user once.
+ */ export function generateApiKeyToken() {
+    const body = randomBytes(24).toString('base64url');
+    const token = `${API_KEY_TOKEN_PREFIX}${body}`;
+    return {
+        token,
+        hash: hashApiKey(token),
+        keyPrefix: `${API_KEY_TOKEN_PREFIX}${body.slice(0, DISPLAY_BODY_CHARS)}…`
+    };
+}
+/** True when the granted scopes include the one an operation requires. */ export function hasScope(granted, required) {
+    return granted.includes(required);
+}
+/** A random public key id (`key_…`), distinct from the secret and its hash. */ export function generateKeyId() {
+    return `key_${randomBytes(9).toString('base64url')}`;
+}
+// ── Storage (Admin SDK) ─────────────────────────────────────────────────────
+function collection() {
+    return firebaseAdmin.app().firestore().collection(API_KEYS_COLLECTION);
+}
+const tsToIso = (value)=>value ? value.toDate().toISOString() : null;
+/** Public projection of a stored key — never includes the hash/doc id. */ export function toPublicApiKey(doc) {
+    var _doc_scopes;
+    return {
+        keyId: doc.keyId,
+        name: doc.name,
+        keyPrefix: doc.keyPrefix,
+        scopes: (_doc_scopes = doc.scopes) != null ? _doc_scopes : [],
+        createdAt: tsToIso(doc.createdAt),
+        lastUsedAt: tsToIso(doc.lastUsedAt),
+        revokedAt: tsToIso(doc.revokedAt),
+        expiresAt: tsToIso(doc.expiresAt)
+    };
+}
+/**
+ * Create a key for an org. Returns the raw `token` (show once) and the public
+ * metadata. Invalid scopes are dropped; at least one valid scope is required.
+ */ export async function mintApiKey(input) {
+    const scopes = normalizeScopes(input.scopes);
+    if (scopes.length === 0) {
+        throw new Error('An API key needs at least one valid scope');
+    }
+    const { Timestamp, FieldValue } = firebaseAdmin.firestore;
+    const { token, hash, keyPrefix } = generateApiKeyToken();
+    const keyId = generateKeyId();
+    const expiresAt = input.expiresAtMs != null ? Timestamp.fromMillis(input.expiresAtMs) : null;
+    const doc = {
+        keyId,
+        orgId: input.orgId,
+        name: input.name.slice(0, 120),
+        keyPrefix,
+        scopes,
+        createdBy: input.createdBy,
+        createdAt: FieldValue.serverTimestamp(),
+        lastUsedAt: null,
+        revokedAt: null,
+        expiresAt
+    };
+    // `create` (not set) so a hash collision can never overwrite another key.
+    await collection().doc(hash).create(doc);
+    return {
+        token,
+        key: {
+            keyId,
+            name: doc.name,
+            keyPrefix,
+            scopes,
+            createdAt: new Date().toISOString(),
+            lastUsedAt: null,
+            revokedAt: null,
+            expiresAt: expiresAt ? expiresAt.toDate().toISOString() : null
+        }
+    };
+}
+/**
+ * Resolve a raw token to its org/scopes, or `null` if it is malformed,
+ * unknown, revoked, or expired. Refreshes `lastUsedAt` at most once a minute
+ * (fire-and-forget) to avoid a write on every request.
+ */ export async function verifyApiKey(token) {
+    var _data_scopes, _data_name;
+    if (!isValidApiKeyFormat(token)) return null;
+    const snap = await collection().doc(hashApiKey(token)).get();
+    if (!snap.exists) return null;
+    const data = snap.data();
+    if (data.revokedAt) return null;
+    const now = Date.now();
+    if (data.expiresAt && data.expiresAt.toMillis() <= now) return null;
+    const lastUsedMs = data.lastUsedAt ? data.lastUsedAt.toMillis() : 0;
+    if (now - lastUsedMs > 60000) {
+        snap.ref.update({
+            lastUsedAt: firebaseAdmin.firestore.FieldValue.serverTimestamp()
+        }).catch(()=>undefined);
+    }
+    return {
+        orgId: data.orgId,
+        keyId: data.keyId,
+        scopes: (_data_scopes = data.scopes) != null ? _data_scopes : [],
+        name: String((_data_name = data.name) != null ? _data_name : '')
+    };
+}
+/** All keys for an org, newest first (metadata only). */ export async function listApiKeys(orgId) {
+    const snap = await collection().where('orgId', '==', orgId).get();
+    return snap.docs.map((doc)=>toPublicApiKey(doc.data())).sort((a, b)=>{
+        var _b_createdAt, _a_createdAt;
+        return ((_b_createdAt = b.createdAt) != null ? _b_createdAt : '').localeCompare((_a_createdAt = a.createdAt) != null ? _a_createdAt : '');
+    });
+}
+/** Revoke a key by its public id. Returns false if not found/already revoked. */ export async function revokeApiKey(orgId, keyId) {
+    const snap = await collection().where('orgId', '==', orgId).get();
+    const match = snap.docs.find((doc)=>doc.data().keyId === keyId);
+    if (!match || match.data().revokedAt) return false;
+    await match.ref.update({
+        revokedAt: firebaseAdmin.firestore.FieldValue.serverTimestamp()
+    });
+    return true;
+}
+
+//# sourceMappingURL=api-keys.js.map

package/src/lib/server/api-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/api-keys.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Customer API keys (AGL-616). Keys authenticate the public REST API\n * (`/api/v1/**`). Only a SHA-256 hash of the key is ever stored — the raw\n * token is shown to the user exactly once, at creation. The Firestore doc id\n * IS the hash, so verification is an O(1) `get()` and the hash never leaves\n * the server (listings return metadata only). The `apiKeys` collection is\n * deny-all in the security rules; all access is Admin-SDK only.\n *\n * The token/hash/format/scope helpers are pure and unit-tested; the storage\n * functions wrap the Admin SDK.\n */\nimport { createHash, randomBytes } from 'node:crypto'\nimport { firebaseAdmin } from './firebase-admin'\n\n/**\n * Scopes a key can be granted, as `resource:action`. Every entry must be\n * enforced by a real endpoint — a mintable scope that grants nothing reads\n * as a broken permission (AGL-899 removed `contacts:write` on those grounds,\n * and AGL-2276 re-added it in the same change that shipped the writes, which\n * is the condition AGL-899 set).\n */\nexport const API_SCOPES = [\n  'datasets:read',\n  'datasets:write',\n  'contacts:read',\n  // AGL-2276. Contacts used to arrive only through the four site capture\n  // points, so an integration that OWNS the customer list upstream — a CRM,\n  // a mailing tool, a migration off another platform — could read the\n  // audience and never add to it. The write is metered against the same\n  // audience bands capture is (AGL-890): `checkContactQuota` on the create,\n  // and the monthly rollup counts `orgs/{orgId}/contacts` whatever wrote\n  // them, so an API-created contact bills exactly like a form-captured one.\n  // The scope covers the create, the tag/notes edit the console's Contacts\n  // page already makes, and the delete — never `email`, which is the dedupe\n  // key, and never `sources`/`interactions`, which are provenance.\n  'contacts:write',\n  'sites:read',\n  // AGL-2462. An integration could write a dataset record over /v1 and had no\n  // way to make a live page show it: `getDatasets` caches for 60s behind\n  // `tenant-data:{hostId}` and the catch-all page is `revalidate = 60`, and\n  // time-based ISR is stale-while-revalidate — so the visitor AFTER the window\n  // can still get the old copy. A cache expiring is not a publish.\n  //\n  // Its OWN scope rather than a `sites:write` covering two very different\n  // powers. Publishing is not a site edit: it changes no stored field, and it\n  // is the one /v1 call whose cost lands on a different service — up to 250\n  // dropped pages, each re-rendering at roughly 40 Firestore reads. A key that\n  // syncs a catalogue should not thereby be able to spend that, and an\n  // integration that only needs to flush its own writes should not have to\n  // hold a scope that could rename the site. Bounded by a per-HOST hourly\n  // budget on top of the per-key request limit, because one call and 250\n  // dropped pages are not the same unit of cost.\n  'sites:publish',\n  // AGL-2465. Everything downstream of a site was automatable and creating\n  // the site was not: `handleSites` 405'd every non-GET, so an agency\n  // onboarding a client could push its datasets, contacts and media and still\n  // had to open a browser to make the site those things go in.\n  //\n  // CREATE ONLY — no rename, no delete, and the omissions are deliberate\n  // rather than unfinished. `hosts/rename` authorizes off the host projection\n  // alone — the member's own entry in `memberRoles`, which must equal\n  // `admin` — and an API key is an ORG credential with no uid, so that gate\n  // has no translation at all; giving it one is a permission decision, not a\n  // port. `hosts/delete` runs\n  // `recursiveDelete` over the whole site plus a storage prefix wipe with no\n  // hold and no soft-delete, and the type-the-name confirmation that guards it\n  // is console UI only — a one-field irreversible delete is the last thing to\n  // put behind a bearer token, and whether it should exist at all is a product\n  // decision that has not been made.\n  //\n  // Replay-safe, which is what actually blocked this: site creation is the\n  // most expensive object here to duplicate — it takes a `hostLimit` slot,\n  // writes `hostIndex` and runs `syncOrgAuthProjections` across every member —\n  // and `/v1` publishes idempotency as a contract. A POST that succeeded\n  // server-side but lost its response now replays the original site rather\n  // than minting a second one.\n  'sites:write',\n  'forms:read',\n  // AGL-2127. A lead sync could READ a submission and never record that it\n  // had — so it re-pushed the same lead on every poll, or kept its own\n  // high-water mark against a list ordered by document id rather than by\n  // time. `read` is the flag the console already toggles on the same\n  // document, so the scope grants exactly the state the integration needs\n  // (plus the delete that lets it purge after export), and nothing that\n  // rewrites what a visitor actually typed.\n  'forms:write',\n  // Commerce and media reads (AGL-1928). Each is separate from `sites:read`\n  // for the same reason `forms:read` is: a key handed to a fulfilment or\n  // accounting integration needs the order history and nothing else, and a\n  // key that syncs a catalogue into a PIM should not thereby be able to read\n  // every form submission a site has ever taken. Read-only on purpose —\n  // writes here move money or stock and want their own decision, in the same\n  // change that ships them (the AGL-899 rule for `contacts:write`).\n  'orders:read',\n  // AGL-2461. The read-only note above says commerce writes wait for \"their\n  // own decision, in the same change that ships them\" because they \"move\n  // money or stock\". Recording a shipment does NEITHER — `fulfill-order.ts`'s\n  // own header says so: \"a forward status flip plus a timeline entry, no\n  // stock moved, no money moved\" — so it is precisely the write that rule\n  // admits, and it is the day-one commerce automation: a 3PL, ShipStation, or\n  // a warehouse's own system marking an order shipped with a tracking number.\n  // A public API that can take an order and never ship it is a fulfilment\n  // dead end.\n  //\n  // Fulfilment ONLY. `cancelled` and `refunded` are refused by name with a\n  // 400: those move stock and money through their own transactions, and this\n  // scope must never become the door around them. The transition rule itself\n  // is not re-implemented here at all — the write goes through the commerce\n  // plugin's own transaction via the order-fulfilment capability registry,\n  // so the API can never write a status the console forbids.\n  'orders:write',\n  'products:read',\n  'media:read',\n  // AGL-2463. `media:read` was the only media scope, so an agency onboarding a\n  // client site could automate everything about that site except putting its\n  // images in it — an integration could LIST the library and never add to it,\n  // which stops the asset pipeline at the one step that matters.\n  //\n  // Create only: no replace, no delete, no edit of an existing file's metadata.\n  // A key handed to a migration tool should be able to fill a library and not\n  // to empty one, and the destructive half wants its own decision in the change\n  // that ships it — the same rule that kept this scope out until now.\n  //\n  // Charged, not free: the create goes through `mediaStorageGate`, the same\n  // helper the console's four ingress routes use, and consumes the existing\n  // per-GB storage dimension rather than inventing a per-upload one.\n  'media:write',\n  // AGL-2606. The CRM v2 collections (AGL-2595) — companies, pipelines,\n  // deals, tasks and activities — sit beside `contacts` and were reachable\n  // only from the console, so the integration that owns the sales process\n  // upstream (a CRM sync, a dialer logging calls, a billing system closing\n  // deals) could read the people and nothing they were doing with them.\n  //\n  // ONE pair for the five resources rather than five, because a key that\n  // needs any of them needs the set: a deal names a company and a contact, a\n  // task names a deal, an activity names all three, and a key that could\n  // read deals but not the pipelines whose stages they cite would hand back\n  // stage ids it cannot explain. The contact's own CRM profile — phone, job\n  // title, company, owner, lifecycle stage — stays under `contacts:*`, since\n  // it is a field of the contact and reads with the contact.\n  //\n  // Reads are org-wide, as every read on this surface is: a key is an\n  // organization credential. Writes name the site they belong to and are\n  // stamped in that site's scope (`crmCreateStamp`), so an API-created deal\n  // lands exactly where a console-created one would, and never wider.\n  'crm:read',\n  'crm:write',\n] as const\n\nexport type ApiScope = (typeof API_SCOPES)[number]\n\n/** Live-key token prefix. A `_test_` variant can follow the same shape later. */\nexport const API_KEY_TOKEN_PREFIX = 'aglyn_sk_'\n\n/** Top-level collection; doc id = the token hash. */\nexport const API_KEYS_COLLECTION = 'apiKeys'\n\n/** How much of the raw token is retained (plaintext) for display/identification. */\nconst DISPLAY_BODY_CHARS = 6\n\n/** Stored document. `createdAt`/`lastUsedAt`/etc. are Firestore Timestamps. */\nexport interface ApiKeyDocument {\n  /** Public, stable id shown in the UI and used for revoke (never the hash). */\n  keyId: string\n  orgId: string\n  name: string\n  /** e.g. `aglyn_sk_ab12cd…` — enough to recognize a key, not to use it. */\n  keyPrefix: string\n  scopes: ApiScope[]\n  createdBy: string\n  createdAt: FirebaseFirestore.Timestamp\n  lastUsedAt: FirebaseFirestore.Timestamp | null\n  revokedAt: FirebaseFirestore.Timestamp | null\n  expiresAt: FirebaseFirestore.Timestamp | null\n}\n\n/** Metadata safe to return to a client (no hash, no raw token). */\nexport interface PublicApiKey {\n  keyId: string\n  name: string\n  keyPrefix: string\n  scopes: ApiScope[]\n  createdAt: string | null\n  lastUsedAt: string | null\n  revokedAt: string | null\n  expiresAt: string | null\n}\n\n/** The resolved principal after a successful key verification. */\nexport interface VerifiedApiKey {\n  orgId: string\n  keyId: string\n  scopes: ApiScope[]\n  /**\n   * The name the organization gave the key — what a feed attributes the\n   * key's writes to (AGL-2632). Every minted key carries one; empty only\n   * for a document written before the field was required.\n   */\n  name: string\n}\n\n// ── Pure helpers (unit-tested; no I/O) ──────────────────────────────────────\n\n/** True if `value` is one of the known scopes. */\nexport function isApiScope(value: string): value is ApiScope {\n  return (API_SCOPES as readonly string[]).includes(value)\n}\n\n/** Keep only valid, de-duplicated scopes, preserving `API_SCOPES` order. */\nexport function normalizeScopes(scopes: readonly string[]): ApiScope[] {\n  const set = new Set(scopes.filter(isApiScope) as ApiScope[])\n  return API_SCOPES.filter((scope) => set.has(scope))\n}\n\n/** SHA-256 hex of a raw token — the Firestore doc id and lookup key. */\nexport function hashApiKey(token: string): string {\n  return createHash('sha256').update(token, 'utf8').digest('hex')\n}\n\n/** Structural check before hashing/looking up — cheap reject of junk input. */\nexport function isValidApiKeyFormat(token: string): boolean {\n  return (\n    typeof token === 'string' &&\n    token.startsWith(API_KEY_TOKEN_PREFIX) &&\n    /^[A-Za-z0-9_-]{24,}$/.test(token.slice(API_KEY_TOKEN_PREFIX.length))\n  )\n}\n\n/**\n * Generate a fresh token plus the derived hash and display prefix. The raw\n * `token` is the only time the secret exists in plaintext — persist the hash,\n * hand the token to the user once.\n */\nexport function generateApiKeyToken(): {\n  token: string\n  hash: string\n  keyPrefix: string\n} {\n  const body = randomBytes(24).toString('base64url')\n  const token = `${API_KEY_TOKEN_PREFIX}${body}`\n  return {\n    token,\n    hash: hashApiKey(token),\n    keyPrefix: `${API_KEY_TOKEN_PREFIX}${body.slice(0, DISPLAY_BODY_CHARS)}…`,\n  }\n}\n\n/** True when the granted scopes include the one an operation requires. */\nexport function hasScope(\n  granted: readonly ApiScope[],\n  required: ApiScope,\n): boolean {\n  return granted.includes(required)\n}\n\n/** A random public key id (`key_…`), distinct from the secret and its hash. */\nexport function generateKeyId(): string {\n  return `key_${randomBytes(9).toString('base64url')}`\n}\n\n// ── Storage (Admin SDK) ─────────────────────────────────────────────────────\n\nfunction collection() {\n  return firebaseAdmin.app().firestore().collection(API_KEYS_COLLECTION)\n}\n\nconst tsToIso = (\n  value: FirebaseFirestore.Timestamp | null | undefined,\n): string | null => (value ? value.toDate().toISOString() : null)\n\n/** Public projection of a stored key — never includes the hash/doc id. */\nexport function toPublicApiKey(doc: ApiKeyDocument): PublicApiKey {\n  return {\n    keyId: doc.keyId,\n    name: doc.name,\n    keyPrefix: doc.keyPrefix,\n    scopes: doc.scopes ?? [],\n    createdAt: tsToIso(doc.createdAt),\n    lastUsedAt: tsToIso(doc.lastUsedAt),\n    revokedAt: tsToIso(doc.revokedAt),\n    expiresAt: tsToIso(doc.expiresAt),\n  }\n}\n\nexport interface MintApiKeyInput {\n  orgId: string\n  name: string\n  scopes: readonly string[]\n  createdBy: string\n  /** Optional absolute expiry, epoch ms. */\n  expiresAtMs?: number | null\n}\n\n/**\n * Create a key for an org. Returns the raw `token` (show once) and the public\n * metadata. Invalid scopes are dropped; at least one valid scope is required.\n */\nexport async function mintApiKey(\n  input: MintApiKeyInput,\n): Promise<{ token: string; key: PublicApiKey }> {\n  const scopes = normalizeScopes(input.scopes)\n  if (scopes.length === 0) {\n    throw new Error('An API key needs at least one valid scope')\n  }\n  const { Timestamp, FieldValue } = firebaseAdmin.firestore\n  const { token, hash, keyPrefix } = generateApiKeyToken()\n  const keyId = generateKeyId()\n  const expiresAt =\n    input.expiresAtMs != null ? Timestamp.fromMillis(input.expiresAtMs) : null\n\n  const doc = {\n    keyId,\n    orgId: input.orgId,\n    name: input.name.slice(0, 120),\n    keyPrefix,\n    scopes,\n    createdBy: input.createdBy,\n    createdAt: FieldValue.serverTimestamp(),\n    lastUsedAt: null,\n    revokedAt: null,\n    expiresAt,\n  }\n  // `create` (not set) so a hash collision can never overwrite another key.\n  await collection().doc(hash).create(doc)\n\n  return {\n    token,\n    key: {\n      keyId,\n      name: doc.name,\n      keyPrefix,\n      scopes,\n      createdAt: new Date().toISOString(),\n      lastUsedAt: null,\n      revokedAt: null,\n      expiresAt: expiresAt ? expiresAt.toDate().toISOString() : null,\n    },\n  }\n}\n\n/**\n * Resolve a raw token to its org/scopes, or `null` if it is malformed,\n * unknown, revoked, or expired. Refreshes `lastUsedAt` at most once a minute\n * (fire-and-forget) to avoid a write on every request.\n */\nexport async function verifyApiKey(\n  token: string,\n): Promise<VerifiedApiKey | null> {\n  if (!isValidApiKeyFormat(token)) return null\n  const snap = await collection().doc(hashApiKey(token)).get()\n  if (!snap.exists) return null\n  const data = snap.data() as ApiKeyDocument\n\n  if (data.revokedAt) return null\n  const now = Date.now()\n  if (data.expiresAt && data.expiresAt.toMillis() <= now) return null\n\n  const lastUsedMs = data.lastUsedAt ? data.lastUsedAt.toMillis() : 0\n  if (now - lastUsedMs > 60_000) {\n    snap.ref\n      .update({ lastUsedAt: firebaseAdmin.firestore.FieldValue.serverTimestamp() })\n      .catch(() => undefined)\n  }\n\n  return {\n    orgId: data.orgId,\n    keyId: data.keyId,\n    scopes: data.scopes ?? [],\n    name: String(data.name ?? ''),\n  }\n}\n\n/** All keys for an org, newest first (metadata only). */\nexport async function listApiKeys(orgId: string): Promise<PublicApiKey[]> {\n  const snap = await collection().where('orgId', '==', orgId).get()\n  return snap.docs\n    .map((doc) => toPublicApiKey(doc.data() as ApiKeyDocument))\n    .sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''))\n}\n\n/** Revoke a key by its public id. Returns false if not found/already revoked. */\nexport async function revokeApiKey(\n  orgId: string,\n  keyId: string,\n): Promise<boolean> {\n  const snap = await collection().where('orgId', '==', orgId).get()\n  const match = snap.docs.find(\n    (doc) => (doc.data() as ApiKeyDocument).keyId === keyId,\n  )\n  if (!match || (match.data() as ApiKeyDocument).revokedAt) return false\n  await match.ref.update({\n    revokedAt: firebaseAdmin.firestore.FieldValue.serverTimestamp(),\n  })\n  return true\n}\n"],"names":["createHash","randomBytes","firebaseAdmin","API_SCOPES","API_KEY_TOKEN_PREFIX","API_KEYS_COLLECTION","DISPLAY_BODY_CHARS","isApiScope","value","includes","normalizeScopes","scopes","set","Set","filter","scope","has","hashApiKey","token","update","digest","isValidApiKeyFormat","startsWith","test","slice","length","generateApiKeyToken","body","toString","hash","keyPrefix","hasScope","granted","required","generateKeyId","collection","app","firestore","tsToIso","toDate","toISOString","toPublicApiKey","doc","keyId","name","createdAt","lastUsedAt","revokedAt","expiresAt","mintApiKey","input","Error","Timestamp","FieldValue","expiresAtMs","fromMillis","orgId","createdBy","serverTimestamp","create","key","Date","verifyApiKey","data","snap","get","exists","now","toMillis","lastUsedMs","ref","catch","undefined","String","listApiKeys","where","docs","map","sort","a","b","localeCompare","revokeApiKey","match","find"],"mappings":"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"}

package/src/lib/server/auth-handoff.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * 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.
+ */
+/** Firestore collection holding pending/authorized handoffs. */
+export declare const AUTH_HANDOFFS_COLLECTION = "authHandoffs";
+/** Name of the host-only verifier cookie the custom domain sets. */
+export declare const HANDOFF_VERIFIER_COOKIE = "__aglyn_handoff";
+/** initiate → authorize. Generous; a pending record grants nothing. */
+export declare const HANDOFF_PENDING_TTL_MS: number;
+/** authorize → redeem. One navigation and one same-origin POST. */
+export declare const HANDOFF_AUTHORIZED_TTL_MS: number;
+export type HandoffStatus = 'pending' | 'authorized' | 'redeemed';
+/** SHA-256 hex, the same shape `hashApiKey` stores. */
+export declare function hashHandoffSecret(value: string): string;
+/**
+ * A `continuePath` that cannot leave the custom domain.
+ *
+ * The handoff lands the user somewhere immediately after signing them in,
+ * which is the worst possible moment to hand control to an attacker-chosen
+ * origin — so this defers to {@link safeSameOriginPath}, which resolves the
+ * value and compares origins instead of testing its shape (AGL-1881).
+ *
+ * This function used to reject `//evil.example` and `/\evil.example` by
+ * inspecting the characters. That list read as complete and was not: the URL
+ * parser deletes tab, LF and CR before parsing, so `/<TAB>/evil.example`
+ * contains neither `//` nor `\` and still resolves to `https://evil.example/`.
+ * Enumerating tricks is the bug; asking the parser is the fix.
+ */
+export declare function safeContinuePath(input: string | null | undefined): string;
+export interface StartedHandoff {
+    requestId: string;
+    /** `V` — goes in the custom domain's own host-only cookie. */
+    verifier: string;
+    expiresAtMs: number;
+}
+/**
+ * Create a `pending` handoff for `targetHost`, returning the id and verifier.
+ *
+ * Called on the custom domain, unauthenticated: nothing about a pending record
+ * is a capability. It names the host the request actually arrived on — never a
+ * host from a parameter — which is what makes the `targetHost` check at
+ * redemption mean anything.
+ */
+export declare function startConsoleHandoff(options: {
+    targetHost: string;
+    orgSlug: string | null;
+    continuePath?: string | null;
+    nowMs?: number;
+}): Promise<StartedHandoff | null>;
+export type AuthorizeRefusal = 'unknown-request' | 'not-pending' | 'expired' | 'host-mismatch' | 'domain-inactive' | 'not-a-member' | 'impersonation';
+export type AuthorizeResult = {
+    ok: true;
+    /** `S` — goes in the return URL's FRAGMENT, never its query. */
+    secret: string;
+    targetHost: string;
+    continuePath: string;
+} | {
+    ok: false;
+    reason: AuthorizeRefusal;
+    orgSlug: string | null;
+};
+/**
+ * Authorize a pending handoff, on the AUTH HOST, for a signed-in user.
+ *
+ * `isMember` is injected rather than resolved here so this module stays free
+ * of the membership model, and so the test can exercise the refusal without a
+ * membership fixture. It receives the target host as well as the slug because
+ * the ORG ID lives on the claim and `resolveConsoleDomain` deliberately never
+ * returns it — a verdict is read by an unauthenticated route. It is called
+ * only after the domain has been shown to be live, so a refusal never reveals
+ * whether an org exists.
+ *
+ * The write flips `pending → authorized` inside {@link consumeOnce}, so a
+ * second authorize of the same id finds `not-pending`. That matters: without
+ * it, an attacker who obtained a request id could keep re-authorizing it and
+ * mint a fresh secret each time the victim signed in.
+ */
+export declare function authorizeConsoleHandoff(options: {
+    requestId: string;
+    uid: string;
+    tenantId?: string | null;
+    impersonated?: boolean;
+    isMember: (context: {
+        targetHost: string;
+        orgSlug: string | null;
+    }) => Promise<boolean>;
+    nowMs?: number;
+}): Promise<AuthorizeResult>;
+export type RedeemRefusal = 'unknown-request' | 'already-redeemed' | 'not-authorized' | 'expired' | 'host-mismatch' | 'bad-secret' | 'bad-verifier' | 'domain-inactive' | 'revoked';
+export type RedeemResult = {
+    ok: true;
+    uid: string;
+    tenantId: string | null;
+    continuePath: string;
+} | {
+    ok: false;
+    reason: RedeemRefusal;
+};
+/**
+ * Consume an authorized handoff, on the CUSTOM DOMAIN.
+ *
+ * Both secrets are required and both are checked INSIDE the transaction, so
+ * the checks cannot be raced against the consume.
+ *
+ * `verifiers` is every value of the `__aglyn_handoff` cookie on the request,
+ * not one. A compromised sibling host under the customer's own apex can set a
+ * `Domain=.acme-agency.com` cookie of the same name, which SHADOWS the
+ * host-only one in the `Cookie` header with no way to tell them apart — the
+ * precise failure AGL-1259 hit with duplicate `__session` cookies. Hashing
+ * every value and accepting if any matches is safe by construction (only the
+ * real `V` hashes to `verifierHash`) and turns a hijack attempt into a no-op
+ * rather than a denial of service.
+ */
+export declare function redeemConsoleHandoff(options: {
+    requestId: string;
+    secret: string;
+    verifiers: string[];
+    requestHost: string;
+    nowMs?: number;
+}): Promise<RedeemResult>;
+/**
+ * `consoleDomains/{host}.sessionEpoch`, or `0` when there is no usable one.
+ *
+ * `0` is returned for every unreadable shape — an unnormalizable host, an
+ * absent document, a Firestore error, a non-finite or non-positive value — and
+ * every caller reads `0` as "this control has nothing to say", i.e. FAILS OPEN.
+ * That is deliberate and matches every other console-domain lookup: the Vercel
+ * allowlist is the boundary and this is defence in depth, so a Firestore blip
+ * must not lock every custom domain out of its own session.
+ *
+ * Note the split with {@link consoleSessionEpochRefuses}: failing open on a
+ * missing EPOCH is not the same as failing open on a missing CREDENTIAL DATE.
+ * A cookie whose `iat` cannot be read is refused, because an undateable
+ * credential cannot be shown to postdate a revocation.
+ */
+export declare function readConsoleSessionEpoch(host: string): Promise<number>;
+/**
+ * The revocation epoch on a console domain (AGL-1353 D6).
+ *
+ * A session cookie minted before the epoch is dead. Bumping `sessionEpoch` —
+ * which `suspendOnDowngrade` and `releaseConsoleDomain` already do — therefore
+ * invalidates every outstanding cookie for that host instantly, at our
+ * boundary. Our boundary is the ONLY place a Firebase session cookie has any
+ * value: it is opaque and can only be cashed by `verifySessionCookie` under
+ * our Admin credentials.
+ *
+ * Fails OPEN on a read error, matching every other console-domain lookup.
+ */
+export declare function consoleSessionEpochRefuses(options: {
+    host: string;
+    cookieIssuedAtMs: number | null;
+}): Promise<boolean>;