@immediately-run/preauth-core 0.1.7 → 0.1.9

package/dist/docLayout.d.ts

@@ -13,6 +13,56 @@ export interface MintSentinels {
  *  of a delegated grant's `parentGrantId`. `::` is delimiter-safe: `appKey` uses
  *  `__` separators and a Firestore `spaceId` is alphanumeric. */
 export declare const grantKey: (appKey: string, spaceId: string) => string;
+/** R3-98 S4 — the principal-aware grant key `(appKey, principal, spaceId)` (design
+ *  05a §3.1/§3.2). Additive: {@link grantKey} is retained for the legacy 2-field
+ *  form. `::` stays delimiter-safe — `appKey` uses `__`, a `spaceId` is alphanumeric,
+ *  and a named principal is lowercase-dotted/hyphenated (CA-3), none containing `::`. */
+export declare const grantKeyWithPrincipal: (appKey: string, principal: string, spaceId: string) => string;
+/** A parsed `parentGrantId` — the pieces the §8.15 revoke cascade reconstructs a
+ *  grant doc path from. `principal` is present only for a 3-field (S4+) key. */
+export interface ParsedGrantKey {
+    appKey: string;
+    spaceId: string;
+    /** The named principal for a 3-field {@link grantKeyWithPrincipal} key; undefined
+     *  for a legacy 2-field {@link grantKey} (the caller defaults to its grandfather
+     *  sentinel). */
+    principal?: string;
+}
+/** R3-98 S4 — ARITY-DETECTING parse of a grant key (design 05a §3.1 step 3 /
+ *  MEDIUM-6). A 3-field key is `appKey::principal::spaceId`; a legacy 2-field key is
+ *  `appKey::spaceId` (principal undefined). This lets the revoke cascade keep
+ *  resolving BOTH legacy and keyed `parentGrantId`s after the re-key — a positional
+ *  `split('::')` would mis-assign a legacy key's `spaceId` to `principal`. A
+ *  malformed key (≠2/≠3 segments) degrades to best-effort `appKey::…::spaceId`
+ *  (first + last), so the cascade fails safe (child self-revokes) rather than
+ *  crashing. */
+export declare const parseGrantKey: (key: string) => ParsedGrantKey;
+/** The doc-id delimiter between a qualifying principal and the spaceId. Safe: a
+ *  named principal is lowercase-dotted/hyphenated (CA-3 reserves `~`) and a
+ *  Firestore spaceId is alphanumeric, so `~` appears in NEITHER — a single,
+ *  unambiguous split point. */
+export declare const GRANT_DOCID_DELIM = "~";
+/** Build a space-grant doc-id (design 05a §3.1 step 2). Pass the QUALIFYING named
+ *  principal to get `${principal}~${spaceId}`; pass `undefined` (stage / legacy /
+ *  no principal) for the bare `spaceId`. The caller resolves "does this principal
+ *  qualify" (site-main maps stage/legacy → undefined) so this stays a pure string
+ *  builder with no sentinel knowledge. */
+export declare const grantDocId: (spaceId: string, qualifyingPrincipal?: string) => string;
+/** A parsed grant doc-id — the §3.5 reader-parse discipline. `principal` is set
+ *  only for a QUALIFIED (`${principal}~${spaceId}`) id; a bare id (a stage/legacy
+ *  grant) yields `{ spaceId }` with `principal` undefined. */
+export interface ParsedGrantDocId {
+    /** The qualifying principal, or undefined for a bare (stage/legacy) doc-id. */
+    principal?: string;
+    spaceId: string;
+}
+/** Parse a space-grant doc-id back into `{ principal?, spaceId }` — the §3.5
+ *  reader-parse discipline every app-space-grant collection reader routes `d.id`
+ *  through so it never mistakes `${principal}~${spaceId}` for a bare spaceId (which
+ *  would corrupt the derived `mountId` and leak grants across principals). Splits
+ *  on the FIRST delimiter; a named principal never contains `~`, so this recovers
+ *  the exact principal + spaceId. A bare id (no delimiter) ⇒ `{ spaceId }`. */
+export declare const parseGrantDocId: (docId: string) => ParsedGrantDocId;
 /** Durable elevated/app-scoped grants expire after 90 days WITHOUT USE; first
  *  use after expiry re-prompts. Baseline needs no grant record, so this never
  *  touches it. */
@@ -31,7 +81,12 @@ export declare const spacePath: (spaceId: string) => DocPath;
 export declare const memberPath: (spaceId: string, grantee: string) => DocPath;
 export declare const userSpacePath: (uid: string, spaceId: string) => DocPath;
 export declare const appKeyPath: (uid: string, appKey: string) => DocPath;
-export declare const appSpacePath: (uid: string, appKey: string, spaceId: string) => DocPath;
+/** `user-app-spaces/{uid}/apps/{appKey}/spaces/{docId}` — the durable §8.7 grant
+ *  doc. R3-98 S5: the doc-id is principal-qualified — pass the QUALIFYING named
+ *  principal for `${principal}~${spaceId}`, or omit it (stage / legacy) for the
+ *  bare `spaceId`. Backward-compatible: a 3-arg call (no principal) yields exactly
+ *  the pre-S5 path, so the backend/CLI stage mint is byte-identical. */
+export declare const appSpacePath: (uid: string, appKey: string, spaceId: string, qualifyingPrincipal?: string) => DocPath;
 export declare const userCountPath: (uid: string) => DocPath;
 export declare const appCountPath: (uid: string, appKey: string) => DocPath;
 /** `spaces/{spaceId}` — the root doc (written WITHOUT merge). */
@@ -50,7 +105,7 @@ export declare const appKeyTouchFields: (s: MintSentinels) => Record<string, unk
 /** `user-app-spaces/{uid}/apps/{appKey}/spaces/{spaceId}` — the durable §8.7
  *  grant doc (merge). `mintPath` defaults to `interactive`; `grantedAt`/`lastUsedAt`
  *  drive the §8.15 90-day-unused expiry. */
-export declare const appSpaceGrantFields: (params: Pick<GrantSpaceParams, "name" | "subtree" | "mode" | "rules" | "declaredUri" | "mintPath" | "parentGrantId">, s: MintSentinels) => Record<string, unknown>;
+export declare const appSpaceGrantFields: (params: Pick<GrantSpaceParams, "name" | "subtree" | "mode" | "rules" | "declaredUri" | "mintPath" | "parentGrantId" | "principal">, s: MintSentinels) => Record<string, unknown>;
 /** Union net:fetch host rules by origin (incoming wins) — the "consent
  *  accumulates" merge both adapters apply before writing the host set. */
 export declare const mergeNetFetchHosts: (existing: readonly NetFetchHost[], incoming: readonly NetFetchHost[]) => NetFetchHost[];

package/dist/docLayout.js

@@ -16,12 +16,70 @@
 // `.set()`/`.update()` is the only thing each adapter does itself. Drift is then
 // impossible without editing a helper both consume.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.appCapabilitiesGrantFields = exports.mergeCapabilities = exports.netFetchGrantFields = exports.mergeNetFetchHosts = exports.appSpaceGrantFields = exports.appKeyTouchFields = exports.appCountFields = exports.userCountFields = exports.ownerUserSpaceFields = exports.ownerMemberFields = exports.spaceDocFields = exports.appCountPath = exports.userCountPath = exports.appSpacePath = exports.appKeyPath = exports.userSpacePath = exports.memberPath = exports.spacePath = exports.defined = exports.granteeId = exports.GRANT_EXPIRY_MS = exports.grantKey = void 0;
+exports.appCapabilitiesGrantFields = exports.mergeCapabilities = exports.netFetchGrantFields = exports.mergeNetFetchHosts = exports.appSpaceGrantFields = exports.appKeyTouchFields = exports.appCountFields = exports.userCountFields = exports.ownerUserSpaceFields = exports.ownerMemberFields = exports.spaceDocFields = exports.appCountPath = exports.userCountPath = exports.appSpacePath = exports.appKeyPath = exports.userSpacePath = exports.memberPath = exports.spacePath = exports.defined = exports.granteeId = exports.GRANT_EXPIRY_MS = exports.parseGrantDocId = exports.grantDocId = exports.GRANT_DOCID_DELIM = exports.parseGrantKey = exports.grantKeyWithPrincipal = exports.grantKey = void 0;
 /** Stable per-user identifier for a grant `(appKey, spaceId)`, used as the value
  *  of a delegated grant's `parentGrantId`. `::` is delimiter-safe: `appKey` uses
  *  `__` separators and a Firestore `spaceId` is alphanumeric. */
 const grantKey = (appKey, spaceId) => `${appKey}::${spaceId}`;
 exports.grantKey = grantKey;
+/** R3-98 S4 — the principal-aware grant key `(appKey, principal, spaceId)` (design
+ *  05a §3.1/§3.2). Additive: {@link grantKey} is retained for the legacy 2-field
+ *  form. `::` stays delimiter-safe — `appKey` uses `__`, a `spaceId` is alphanumeric,
+ *  and a named principal is lowercase-dotted/hyphenated (CA-3), none containing `::`. */
+const grantKeyWithPrincipal = (appKey, principal, spaceId) => `${appKey}::${principal}::${spaceId}`;
+exports.grantKeyWithPrincipal = grantKeyWithPrincipal;
+/** R3-98 S4 — ARITY-DETECTING parse of a grant key (design 05a §3.1 step 3 /
+ *  MEDIUM-6). A 3-field key is `appKey::principal::spaceId`; a legacy 2-field key is
+ *  `appKey::spaceId` (principal undefined). This lets the revoke cascade keep
+ *  resolving BOTH legacy and keyed `parentGrantId`s after the re-key — a positional
+ *  `split('::')` would mis-assign a legacy key's `spaceId` to `principal`. A
+ *  malformed key (≠2/≠3 segments) degrades to best-effort `appKey::…::spaceId`
+ *  (first + last), so the cascade fails safe (child self-revokes) rather than
+ *  crashing. */
+const parseGrantKey = (key) => {
+    const parts = key.split('::');
+    if (parts.length === 3) {
+        return { appKey: parts[0], principal: parts[1], spaceId: parts[2] };
+    }
+    // Legacy 2-field, or malformed → first segment is the appKey, last the spaceId.
+    return { appKey: parts[0], spaceId: parts[parts.length - 1] };
+};
+exports.parseGrantKey = parseGrantKey;
+// --- R3-98 S5 — the principal-qualified space-grant doc-id (design 05a §3.1/§3.5) --
+//
+// A space grant's Firestore doc-id encodes the named principal it was minted
+// under, so two principals granting the SAME space live at DIFFERENT docs and are
+// invisible to each other (structural disjointness). The rule (design 05a §3.1
+// step 2): a **qualifying** (real, named) principal → `${principal}~${spaceId}`;
+// the **stage** principal, a **legacy** (no-principal) grant, or none → the bare
+// `spaceId`, so no existing/stage doc ever moves. This module is GRAMMAR ONLY: the
+// caller decides which principals qualify (site-main owns the stage/legacy
+// sentinels — a principal it treats as non-qualifying is passed as `undefined`).
+/** The doc-id delimiter between a qualifying principal and the spaceId. Safe: a
+ *  named principal is lowercase-dotted/hyphenated (CA-3 reserves `~`) and a
+ *  Firestore spaceId is alphanumeric, so `~` appears in NEITHER — a single,
+ *  unambiguous split point. */
+exports.GRANT_DOCID_DELIM = '~';
+/** Build a space-grant doc-id (design 05a §3.1 step 2). Pass the QUALIFYING named
+ *  principal to get `${principal}~${spaceId}`; pass `undefined` (stage / legacy /
+ *  no principal) for the bare `spaceId`. The caller resolves "does this principal
+ *  qualify" (site-main maps stage/legacy → undefined) so this stays a pure string
+ *  builder with no sentinel knowledge. */
+const grantDocId = (spaceId, qualifyingPrincipal) => qualifyingPrincipal ? `${qualifyingPrincipal}${exports.GRANT_DOCID_DELIM}${spaceId}` : spaceId;
+exports.grantDocId = grantDocId;
+/** Parse a space-grant doc-id back into `{ principal?, spaceId }` — the §3.5
+ *  reader-parse discipline every app-space-grant collection reader routes `d.id`
+ *  through so it never mistakes `${principal}~${spaceId}` for a bare spaceId (which
+ *  would corrupt the derived `mountId` and leak grants across principals). Splits
+ *  on the FIRST delimiter; a named principal never contains `~`, so this recovers
+ *  the exact principal + spaceId. A bare id (no delimiter) ⇒ `{ spaceId }`. */
+const parseGrantDocId = (docId) => {
+    const i = docId.indexOf(exports.GRANT_DOCID_DELIM);
+    return i === -1
+        ? { spaceId: docId }
+        : { principal: docId.slice(0, i), spaceId: docId.slice(i + 1) };
+};
+exports.parseGrantDocId = parseGrantDocId;
 /** Durable elevated/app-scoped grants expire after 90 days WITHOUT USE; first
  *  use after expiry re-prompts. Baseline needs no grant record, so this never
  *  touches it. */
@@ -62,13 +120,18 @@ const appKeyPath = (uid, appKey) => [
     appKey,
 ];
 exports.appKeyPath = appKeyPath;
-const appSpacePath = (uid, appKey, spaceId) => [
+/** `user-app-spaces/{uid}/apps/{appKey}/spaces/{docId}` — the durable §8.7 grant
+ *  doc. R3-98 S5: the doc-id is principal-qualified — pass the QUALIFYING named
+ *  principal for `${principal}~${spaceId}`, or omit it (stage / legacy) for the
+ *  bare `spaceId`. Backward-compatible: a 3-arg call (no principal) yields exactly
+ *  the pre-S5 path, so the backend/CLI stage mint is byte-identical. */
+const appSpacePath = (uid, appKey, spaceId, qualifyingPrincipal) => [
     'user-app-spaces',
     uid,
     'apps',
     appKey,
     'spaces',
-    spaceId,
+    (0, exports.grantDocId)(spaceId, qualifyingPrincipal),
 ];
 exports.appSpacePath = appSpacePath;
 const userCountPath = (uid) => ['space-counts', uid];
@@ -123,6 +186,11 @@ const appSpaceGrantFields = (params, s) => (0, exports.defined)({
     grantedAt: s.serverTimestamp(),
     lastUsedAt: s.serverTimestamp(),
     name: params.name,
+    // R3-98 S3/S4 — the named principal this grant was minted under (design 05a
+    // §3.1). `defined()` omits it when absent, so a legacy/unkeyed mint writes no
+    // `principal` field and is grandfathered at the gate (both adapters stamp it
+    // identically, keeping the byte-identical-doc guarantee).
+    principal: params.principal,
     // UI_AS_APPS_SPEC §8.7: `rules` is authoritative; `subtree`/`mode` are kept as the
     // deprecated `rules[0]` mirror for not-yet-migrated readers. When no rule-set
     // is given, derive a single-rule set from the legacy scope so the backend

package/dist/port.d.ts

@@ -60,6 +60,11 @@ export interface GrantSpaceParams {
     mintPath?: MintPath;
     /** §8.15 — parent `grantKey` for an M2 `delegated` grant. */
     parentGrantId?: string;
+    /** R3-98 S3/S4 — the **named principal** this grant is minted under (design 05a
+     *  §3.1). Written as the `principal` field so the mount-admission gate re-checks
+     *  it (a grant fires only under the principal it was minted with). Optional +
+     *  additive: omitted ⇒ no field ⇒ a legacy/grandfathered grant. */
+    principal?: string;
 }
 /** Parameters for `MintStore.grantNetFetchHosts` — the per-(user, app) granted
  *  host set, the grant half of the `manifest ∩ grant` net:fetch allowlist. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/preauth-core",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "The shared §8.9 pre-auth target check + the single grant-mint path (mintConsentedGrants) + the capability vocabulary + the byte-faithful grant/space/net-fetch document layout. Consumed by site-main (browser Firestore) and the backend (admin Firestore) so there is ONE gate, ONE mint path, ONE wire layout.",
   "license": "UNLICENSED",
   "repository": {