@immediately-run/preauth-core 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @immediately-run/preauth-core
+
+The shared **pre-authorization core** for immediately.run. It exists to make one
+sentence a structural fact:
+
+> Every surface that pre-authorizes or mints a durable capability grant —
+> site-main's M3 consent screen, its M1 settings pre-auth, the backend
+> `POST /preauth` executor, and the `immediately-run preauth` CLI — drives the
+> **same** §8.9 target check and the **same** mint path, writing **byte-identical**
+> Firestore documents. Not a second copy of any of them.
+
+Spec: `UI_AS_APPS_SPEC.md` §8.9 (target check), §8.15 (M1 pre-authorization),
+§8.6/§8.7 (the durable grant set). Plan: `docs/plans/cli-preauth-shared-core.md`.
+
+## What's in here (pure TS, zero runtime deps, no React, no Firebase)
+
+| Module | Surface |
+|---|---|
+| `capabilities` | The capability vocabulary — the **single source of truth** (`CAPABILITIES`, `isAppScoped` / `isBaseline` / `isKnownCapability`, the version gate). site-main re-exports it; the backend imports the same predicates. The §8.9 gate's correctness IS this classification, so there is exactly one. |
+| `port` | `MintStore` — the 3-method persistence port `mintConsentedGrants` calls (`createSpace`, `grantSpaceToApp`, `grantNetFetchHosts`) + its param/domain types (`GrantMode`, `MintPath`, `NetFetchHost`, …). |
+| `docLayout` | The byte-faithful Firestore **paths + field builders** (`grantKey`, `GRANT_EXPIRY_MS`, the grant/space/net-fetch document builders). Each store adapter injects only its SDK's timestamp/increment sentinels and does the raw `.set()`; drift is impossible without editing a helper both consume. |
+| `bootConsent` | `mintConsentedGrants` — the ONE mint path. Environment-neutral: a caller passes `onError` instead of the core logging with a host-specific prefix. |
+| `m1PreAuth` | `planPreAuthCapabilities` / `isPreAuthClean` (the pure §8.9 target check) + `applyPreAuth` (validate-then-mint, all-or-nothing). |
+
+## Consuming it
+
+Via the **`file:` sibling pattern** site-main already uses for the sandpack fork:
+
+```jsonc
+// consumer package.json
+"@immediately-run/preauth-core": "file:../immediately-run-preauth-core"
+```
+
+The built `dist/` is committed so consumers resolve the package without a separate
+build step. After editing `src/`, rebuild:
+
+```bash
+npm run build   # tsc -> dist/ (JS + .d.ts)
+npm test        # jest — the §8.9 gate, the hostile-policy property, the wire layout
+npm run lint
+```

package/dist/bootConsent.d.ts

@@ -0,0 +1,42 @@
+import type { GrantMode, MintPath, MintStore, NetFetchHost } from './port';
+/** A consent-screen selection (structurally `MountConsentSelection` from
+ *  site-main's editor layer; redefined here so this layer stays UI-free). */
+export type ConsentSelection = {
+    uri: string;
+    mode: GrantMode;
+    kind: 'pick';
+    spaceId: string;
+    name?: string;
+} | {
+    uri: string;
+    mode: GrantMode;
+    kind: 'create';
+    name?: string;
+};
+export interface MintResult {
+    /** False if ANY grant failed to mint — the caller treats the start as failed. */
+    ok: boolean;
+    /** Whether the net:fetch host grant succeeded (vacuously true when none was
+     *  requested) — the post-boot caller lifts the frame cap on this alone, even
+     *  if a mount selection failed (matching its historical behavior). */
+    netFetchOk: boolean;
+    /** Successfully minted per-selection space ids (for post-boot provisioning). */
+    minted: {
+        selection: ConsentSelection;
+        spaceId: string;
+    }[];
+}
+/** Observe a per-item mint failure (logging only — authority is unaffected). The
+ *  `ctx` is a stable English phrase; the host decides how/whether to log it. */
+export type MintErrorSink = (ctx: string, err: unknown) => void;
+/**
+ * Turn an Allow choice into durable grants: net:fetch hosts (all-or-nothing —
+ * the screen showed exactly these), then per mount selection create-or-bind the
+ * space to its slot and record the §8.7 grant. Never throws; per-item failures
+ * are surfaced through `ok`/`netFetchOk` (and `onError`, if provided).
+ *
+ * The durable §8.7 grant IS the binding now (no separate slot): `declaredUri`
+ * records which §11.4 declared mount it satisfies, so a later boot re-provisions
+ * it without re-consent.
+ */
+export declare function mintConsentedGrants(store: MintStore, uid: string, appKey: string, selections: readonly ConsentSelection[], netFetchHosts: readonly NetFetchHost[], mintPath?: MintPath, onError?: MintErrorSink): Promise<MintResult>;

package/dist/bootConsent.js

@@ -0,0 +1,67 @@
+"use strict";
+// The ONE grant-mint path (UI_AS_APPS_SPEC §8.15). `mintConsentedGrants` turns a
+// consent choice into durable §8.7/§8.15 grants. It is shared by EVERY surface
+// that records a grant so they cannot drift:
+//   - site-main's before-boot gate + the post-boot fallback (SandboxListener) at
+//     `interactive` (M3) provenance,
+//   - the M1 pre-auth write path (`applyPreAuth`) at `policy` provenance, in both
+//     the browser (settings UI) and the backend `POST /preauth` executor.
+//
+// `mintPath` only stamps the §8.7 grant's PROVENANCE (the §8.11 audit label +
+// revoke-cascade key); it does not change WHAT is minted — the §8.9 target check
+// that bounds M1 lives in its caller (`m1PreAuth.ts`).
+//
+// Pure orchestration over the narrow `MintStore` port (3 methods). No React, no
+// Firebase, no environment-specific logging: a caller passes `onError` to observe
+// per-item failures (site-main wraps it with its `[Main-iframe]` logger; the
+// backend logs with its own prefix), so this module never masquerades as a
+// particular runtime.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mintConsentedGrants = mintConsentedGrants;
+/**
+ * Turn an Allow choice into durable grants: net:fetch hosts (all-or-nothing —
+ * the screen showed exactly these), then per mount selection create-or-bind the
+ * space to its slot and record the §8.7 grant. Never throws; per-item failures
+ * are surfaced through `ok`/`netFetchOk` (and `onError`, if provided).
+ *
+ * The durable §8.7 grant IS the binding now (no separate slot): `declaredUri`
+ * records which §11.4 declared mount it satisfies, so a later boot re-provisions
+ * it without re-consent.
+ */
+async function mintConsentedGrants(store, uid, appKey, selections, netFetchHosts, mintPath = 'interactive', onError) {
+    let ok = true;
+    let netFetchOk = true;
+    if (netFetchHosts.length > 0) {
+        try {
+            await store.grantNetFetchHosts({ uid, appKey, hosts: netFetchHosts });
+        }
+        catch (err) {
+            onError?.('net:fetch grant failed', err);
+            ok = false;
+            netFetchOk = false;
+        }
+    }
+    const minted = [];
+    for (const sel of selections) {
+        try {
+            const spaceId = sel.kind === 'create'
+                ? await store.createSpace({ owner: uid, name: sel.name, appKey })
+                : sel.spaceId;
+            await store.grantSpaceToApp({
+                uid,
+                appKey,
+                spaceId,
+                name: sel.name,
+                mode: sel.mode,
+                declaredUri: sel.uri,
+                mintPath,
+            });
+            minted.push({ selection: sel, spaceId });
+        }
+        catch (err) {
+            onError?.('consent grant minting failed', err);
+            ok = false;
+        }
+    }
+    return { ok, netFetchOk, minted };
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,57 @@
+export type CapabilityKind = 'read' | 'action';
+export type CapabilityTier = 'baseline' | 'elevated' | 'first-party-only';
+export type Capability = 'theme:read' | 'theme:set' | 'auth:status' | 'auth:identity' | 'route:read' | 'formFactor:read' | 'mounts:read' | 'spaces:app' | 'spaces:user' | 'spaces:admin' | 'settings:app' | 'settings:fork' | 'settings:all' | 'contribute:self' | 'contribute:any' | 'contribute:direct' | 'editor:read' | 'editor:open' | 'editor:write' | 'editor:document' | 'editor:requestEdit' | 'vcs:read' | 'vcs:reset' | 'dnd:source' | 'catalog:read' | 'commands:read' | 'commands:run' | 'ipc' | 'task:invoke' | 'net:fetch' | 'secrets:add' | 'secrets:list' | 'secrets:revoke' | 'agent:session';
+export interface CapabilityDef {
+    kind: CapabilityKind;
+    tier: CapabilityTier;
+    /** Lowest platform/registry version that knows this capability (§5.11). */
+    since: string;
+    /** Carries a bounded argument set (host gate checks verb AND argument). */
+    parameterized?: boolean;
+    /** **App-scoped** consent-path annotation on the ELEVATED tier (NOT a fourth
+     *  tier — CAPABILITY_REFERENCE §"How to read this", §6a CR-1). An app-scoped
+     *  elevated capability can be EARNED by a URL-loaded/previewed app via lazy
+     *  first-use or manifest-`requests` consent and recorded as a per-`(user,
+     *  appKey)` grant; non-app-scoped elevated caps are never earnable that way
+     *  (region binding only). The app-scoped set is `net:fetch`, `task:invoke`, and
+     *  `contribute:self` (decision #1 — its baseline→elevated reclassification landed
+     *  in R3-33d; the durable grant participates in the §8.15 90-day expiry like any
+     *  app-scoped grant). */
+    appScoped?: boolean;
+    /** Render this capability's consent line with the platform's **maximally-
+     *  explicit** (scariest) styling, never bundled into a combined prompt
+     *  (decision #2). The most dangerous writes carry it: `contribute:direct`
+     *  (commit without review) and `editor:write` (mutate the working tree).
+     *  Independent of tier — it governs HOW the line is shown, not WHO may hold the
+     *  capability (a first-party-only cap is still refused to a fork regardless). */
+    maximallyExplicit?: boolean;
+}
+export declare const CAPABILITIES: Record<Capability, CapabilityDef>;
+/** The current registry/vocabulary version (§5.11). Bumped to 1.2.0 with the
+ *  per-user settings-space capabilities (`settings:app`/`settings:fork`/
+ *  `settings:all`), mirroring capabilities.json. */
+export declare const REGISTRY_VERSION = "1.2.0";
+/** Is `cap` a known kernel capability? (Closed vocabulary — §5.12.) */
+export declare function isKnownCapability(cap: string): cap is Capability;
+export declare function tierOf(cap: Capability): CapabilityTier;
+/** Baseline = what the previewed app and any unconsented binding may hold. */
+export declare const BASELINE_CAPABILITIES: readonly Capability[];
+export declare function isBaseline(cap: Capability): boolean;
+/** App-scoped consentables — the elevated caps a previewed/forked app may EARN
+ *  via lazy first-use or manifest-`requests` consent (§8.9/§8.15), as opposed to
+ *  region-binding-only elevated caps. (`contribute:self` joined this set in R3-33d
+ *  per decision #1.) */
+export declare const APP_SCOPED_CAPABILITIES: readonly Capability[];
+export declare function isAppScoped(cap: Capability): boolean;
+/** Compare dotted numeric versions: <0 if a<b, 0 if equal, >0 if a>b. Missing
+ *  segments are treated as 0 ("1.2" === "1.2.0"); non-numeric segments as 0. */
+export declare function compareVersions(a: string, b: string): number;
+/** A capability is supported iff it is known AND its `since` ≤ the host version. */
+export declare function isSupportedCapability(cap: string, hostVersion?: string): boolean;
+/**
+ * The subset of `caps` this host cannot enforce — unknown to its vocabulary, or
+ * declared at a `since` newer than `hostVersion`. A non-empty result means the
+ * region must refuse to mount with "update immediately.run (missing: …)" (T26).
+ * `hostVersion` is injectable so an older host can be simulated in tests.
+ */
+export declare function unsupportedCapabilities(caps: readonly string[], hostVersion?: string): string[];

package/dist/capabilities.js

@@ -0,0 +1,217 @@
+"use strict";
+// The capability-definition registry — the KERNEL source of truth
+// (UI_AS_APPS_SPEC §5.11 / §8.2). Capabilities are a CLOSED vocabulary: apps
+// cannot mint one, only be granted one. This module mirrors docs/capabilities.json
+// (the machine-readable companion); the host build is authoritative.
+//
+// Two enforcement points consume this (later slices): reads are gated per-grant
+// with a view() projection on a channel (§8.3); actions are gated before the
+// handler (§8.4). Parameterized capabilities additionally bound an argument set.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_SCOPED_CAPABILITIES = exports.BASELINE_CAPABILITIES = exports.REGISTRY_VERSION = exports.CAPABILITIES = void 0;
+exports.isKnownCapability = isKnownCapability;
+exports.tierOf = tierOf;
+exports.isBaseline = isBaseline;
+exports.isAppScoped = isAppScoped;
+exports.compareVersions = compareVersions;
+exports.isSupportedCapability = isSupportedCapability;
+exports.unsupportedCapabilities = unsupportedCapabilities;
+exports.CAPABILITIES = {
+    'theme:read': { kind: 'read', tier: 'baseline', since: '1.0.0' },
+    'theme:set': { kind: 'action', tier: 'elevated', since: '1.0.0' },
+    'auth:status': { kind: 'read', tier: 'baseline', since: '1.0.0' },
+    'auth:identity': { kind: 'read', tier: 'elevated', since: '1.0.0' },
+    'route:read': { kind: 'read', tier: 'baseline', since: '1.0.0' },
+    'formFactor:read': { kind: 'read', tier: 'baseline', since: '1.0.0' },
+    'mounts:read': { kind: 'read', tier: 'baseline', since: '1.0.0' },
+    'spaces:app': { kind: 'action', tier: 'baseline', since: '1.0.0', parameterized: true },
+    'spaces:user': { kind: 'action', tier: 'elevated', since: '1.0.0' },
+    'spaces:admin': { kind: 'action', tier: 'elevated', since: '1.0.0' },
+    // Per-user settings space (UI_AS_APPS_SPEC §3.3/§3.5/§8.2; settings-space plan).
+    // The app's OWN `~/.config`-style subdir, auto-provisioned + chroot'd by appKey.
+    // Baseline: every app may open its own config with no consent (the host derives
+    // the appKey from the caller, so a different `settings:` locator can't be named).
+    'settings:app': { kind: 'action', tier: 'baseline', since: '1.2.0' },
+    // One-time SEED of the declared `forkOf` parent's settings into the app's own
+    // subdir (§3.4 lineage). Baseline action — the target is locked to the manifest
+    // `forkOf`, so it can never name another app — but the HANDLER gates each call on
+    // a user confirm (full explicit consent when cross-owner, a light confirm when
+    // the same owner published both apps). The consent is a per-action prompt, not a
+    // durable §8.15 grant (the copy lands in the app's own dir; nothing to revoke).
+    'settings:fork': { kind: 'action', tier: 'baseline', since: '1.2.0' },
+    // Mount ANY app's settings subdir / enumerate the whole `settings-store/{uid}`
+    // tree — the filesystem-manager ("file commander") surface. Permanently
+    // first-party-only: cross-app config is an activity oracle (like a future
+    // `mounts:registry`), so a fork/preview can never hold it.
+    'settings:all': { kind: 'action', tier: 'first-party-only', since: '1.2.0' },
+    'contribute:self': { kind: 'action', tier: 'elevated', since: '1.0.0', appScoped: true },
+    'contribute:any': { kind: 'action', tier: 'elevated', since: '1.0.0', parameterized: true },
+    // Decision #2 (R3-33d, landed): contribute:direct is the platform's scariest
+    // write, rendered maximally-explicit. The tier is now **elevated/consentable**
+    // (no longer first-party-only) so source-control panels stay forkable (value 4) —
+    // a fork CAN hold it, but only behind the distinct scary consent line, never
+    // bundled. `maximallyExplicit` (not the tier) is what keeps the line scary.
+    'contribute:direct': { kind: 'action', tier: 'elevated', since: '1.0.0', parameterized: true, maximallyExplicit: true },
+    'editor:read': { kind: 'read', tier: 'elevated', since: '1.0.0' },
+    // Ask the host to open a working-tree file in the CodeMirror editor (§4 — the
+    // file explorer's click-to-open). An INTENT, not editor ownership (§2): the host
+    // validates the path and drives Sandpack. Elevated — it moves the host's focus,
+    // so a previewed app must not hold it; only a consented/build-default binding.
+    'editor:open': { kind: 'action', tier: 'elevated', since: '1.0.0' },
+    // Mutate the editor session's working tree — create/delete/rename/upload a file
+    // (migrate-sidebars Phase 04, EDITOR_AS_APP_SPEC §5.2). A NARROW, per-path gated
+    // action: the file explorer NAMES a path and the HOST performs the COW write
+    // (and notifies Sandpack) — the COW/journal stays in the kernel (§2/§4). The
+    // explorer holds no working-tree write PORT (that broad authority is the
+    // editor app's `editor:document`); it must ask. **Elevated, not first-party-only**
+    // (EDITOR_AS_APP_SPEC §5.1 forkability rule): mutating the user's OWN working copy
+    // does not escape the user's session (no push, no host token, no cross-user reach —
+    // saves stay separately gated, the diff is host-computed), so it is a consentable
+    // grant a user may extend to a fork of the file explorer. `first-party-only` is
+    // reserved for session-ESCAPING authority (e.g. `contribute:direct`).
+    // Decision #2: editor:write is consentable (elevated, forkable — mutating the
+    // user's OWN working copy doesn't escape their session), but behind the
+    // maximally-explicit scary line.
+    'editor:write': { kind: 'action', tier: 'elevated', since: '1.0.0', maximallyExplicit: true },
+    // The editor APP's own session-management capability (EDITOR_AS_APP_SPEC §5.1;
+    // editor-as-app plan Phase 03). Gates the `protocol-editor close`/`setActive`
+    // intents — mutating the editor's OWN open-tab set + active file, which only the
+    // bound editor should drive (NOT the file explorer, which holds `editor:open` to
+    // *ask* the host to open a file, a distinct cross-app intent). Elevated and
+    // forkable via consent: managing the user's own editor view does not escape their
+    // session (no push, no token, no cross-user reach), so a user may extend it to a
+    // forked editor. It will additionally gate the editor app's session/diagnostics
+    // channels as those land (plan Phase 02). NOT the rw working-tree port — that is
+    // the region property `exposesWorkingTree:'rw'`, not this capability.
+    'editor:document': { kind: 'action', tier: 'elevated', since: '1.1.0' },
+    // Enter the EDIT EXPERIENCE for the running app — the present→edit transition
+    // (`/present/...` → `/edit/...`) an app cannot make itself (EDITOR_FIRST_EDITING_SPEC
+    // §6 Delta A). An INTENT (§2): the host performs the visible, user-observable
+    // navigation and draws all editor chrome; the app never navigates or paints chrome.
+    //
+    // Tier — BASELINE, deliberately, and only safe because the transition is STRICTLY
+    // self-scoped: the HANDLER reads only a same-repo, traversal-free `path` and
+    // navigates within the CURRENT route (it cannot be pointed at another repo — the
+    // gate validates the `path` shape, T4). Unlike `editor:open` (elevated — it can
+    // yank focus to an ARBITRARY file from a hostile preview), entering edit on the
+    // repo the user is ALREADY viewing is no escalation: edit mode adds host-drawn
+    // chrome around the same sandboxed app, granting it NO new capability, and "view
+    // your own source" is already the §0 promise. Baseline is also the ONLY tier that
+    // lets a standalone present-mode app (which holds only baseline) offer an "edit
+    // this" affordance instead of shipping a bespoke editor — the whole point of the
+    // delta. **PROPOSED tier, pending capability-owner sign-off (EDITOR_FIRST_EDITING_
+    // SPEC §8 open question #1):** flipping to elevated is a one-token change here.
+    'editor:requestEdit': { kind: 'action', tier: 'baseline', since: '1.1.0' },
+    // Source-control state read surface (migrate-sidebars Phase 05) — the diff
+    // summary + branch info + open-PR list the `panel.contribute` app needs to reach
+    // parity with the native `SourceControlPanel`. Elevated: it exposes the repo's
+    // branch/PR/diff state (no token ever crosses — derived host-side), so a
+    // baseline/previewed frame gets an empty `VcsState`, never a leak.
+    'vcs:read': { kind: 'read', tier: 'elevated', since: '1.1.0' },
+    // Discard the working tree — `resetWorkingTree()` wipes the COW writable layer +
+    // clears the journal, destroying the user's UNSAVED work irreversibly and
+    // UNREVIEWABLY. **First-party-only** (the first cap to re-enter this tier after
+    // R3-33d emptied it): only a pinned build-default `panel.contribute` binding may
+    // hold it — a fork/preview/third-party binding can NEVER discard the user's work,
+    // enforced by tier (`buildConsent` refuses it to a non-first-party binding,
+    // `overridePolicy` strips it on a repoint). Marked maximally-explicit so the one
+    // first-party line that does carry it renders with the scariest styling.
+    'vcs:reset': { kind: 'action', tier: 'first-party-only', since: '1.1.0', maximallyExplicit: true },
+    // Initiate a host-mediated cross-app DRAG-OUT into the previewed app
+    // (FILE_EXPLORER_SPEC §7, R3-83). The source app calls `startItemDrag(item)`;
+    // the host draws the trusted drag ghost, tracks the pointer across the
+    // cross-origin iframe boundary (which native HTML5 DnD cannot cross), and on a
+    // drop over the preview delivers `{ item, from, position }` to a SUBSCRIBED
+    // receiver. Synthesizing a drag INTO a sibling app is an injection / clickjacking
+    // primitive (FE-DND-1), so this is **first-party-only**: only a pinned
+    // build-default chrome binding (the file explorer) may hold it — a fork / preview
+    // / third-party binding can NEVER initiate a cross-app drag, enforced by tier
+    // (`buildConsent` refuses it to a non-first-party binding, never offering a
+    // consent line, exactly like `vcs:reset`). Marked maximally-explicit so the one
+    // first-party line that carries it renders with the scariest styling (same tier
+    // as `editor:open`/`editor:write`/`vcs:reset`). Receiving a drop needs NO new
+    // grant — the previewed app opts in by subscribing (`onItemDrop`).
+    'dnd:source': { kind: 'action', tier: 'first-party-only', since: '1.2.0', maximallyExplicit: true },
+    // The §5.5 method catalog (the app's own filtered RPC surface) — baseline:
+    // every app may discover what IT can call; the list is grant-filtered so it
+    // reveals nothing the app couldn't already invoke.
+    'catalog:read': { kind: 'read', tier: 'baseline', since: '1.0.0' },
+    'commands:read': { kind: 'read', tier: 'elevated', since: '1.0.0' },
+    'commands:run': { kind: 'action', tier: 'elevated', since: '1.0.0' },
+    ipc: { kind: 'action', tier: 'elevated', since: '1.0.0', parameterized: true },
+    // Invoke another app via a task contract (§5.7). Elevated: summoning overlays +
+    // delegating file caps is real authority. Parameterized — the task set is bounded
+    // by the app's manifest `invokes` declaration (§5.8), enforced in the handler.
+    'task:invoke': { kind: 'action', tier: 'elevated', since: '1.0.0', parameterized: true, appScoped: true },
+    'net:fetch': { kind: 'action', tier: 'elevated', since: '1.0.0', parameterized: true, appScoped: true },
+    // Host-owned secret store (SECRETS_SPEC §4). All elevated; the value is never
+    // readable by any app (`secrets:list` exposes metadata only). `secrets:add`
+    // opens a host-drawn modal; `secrets:revoke` deletes + cascades use-grants. The
+    // per-(app,secret) USE grant is NOT a capability row — it is minted via the
+    // `requestSecret` powerbox (gated by `net:fetch`, since a secret is only usable
+    // through §6 injection).
+    'secrets:add': { kind: 'action', tier: 'elevated', since: '1.1.0' },
+    'secrets:list': { kind: 'read', tier: 'elevated', since: '1.1.0' },
+    'secrets:revoke': { kind: 'action', tier: 'elevated', since: '1.1.0' },
+    'agent:session': { kind: 'action', tier: 'elevated', since: '1.0.0' },
+};
+/** The current registry/vocabulary version (§5.11). Bumped to 1.2.0 with the
+ *  per-user settings-space capabilities (`settings:app`/`settings:fork`/
+ *  `settings:all`), mirroring capabilities.json. */
+exports.REGISTRY_VERSION = '1.2.0';
+/** Is `cap` a known kernel capability? (Closed vocabulary — §5.12.) */
+function isKnownCapability(cap) {
+    return Object.prototype.hasOwnProperty.call(exports.CAPABILITIES, cap);
+}
+function tierOf(cap) {
+    return exports.CAPABILITIES[cap].tier;
+}
+/** Baseline = what the previewed app and any unconsented binding may hold. */
+exports.BASELINE_CAPABILITIES = Object.keys(exports.CAPABILITIES).filter((c) => exports.CAPABILITIES[c].tier === 'baseline');
+function isBaseline(cap) {
+    return exports.CAPABILITIES[cap].tier === 'baseline';
+}
+/** App-scoped consentables — the elevated caps a previewed/forked app may EARN
+ *  via lazy first-use or manifest-`requests` consent (§8.9/§8.15), as opposed to
+ *  region-binding-only elevated caps. (`contribute:self` joined this set in R3-33d
+ *  per decision #1.) */
+exports.APP_SCOPED_CAPABILITIES = Object.keys(exports.CAPABILITIES).filter((c) => exports.CAPABILITIES[c].appScoped === true);
+function isAppScoped(cap) {
+    return exports.CAPABILITIES[cap].appScoped === true;
+}
+// ── §5.11 capability version gate (threat T26) ──────────────────────────────
+//
+// Each capability declares the lowest registry version that knows it (`since`).
+// A binding may reference a capability this host is too old to enforce (an
+// override / synced binding authored against a newer immediately.run). Mounting
+// it would mount-then-break, so the loader must refuse with an actionable
+// "update immediately.run" message (§6.3) — never a half-working region.
+/** Compare dotted numeric versions: <0 if a<b, 0 if equal, >0 if a>b. Missing
+ *  segments are treated as 0 ("1.2" === "1.2.0"); non-numeric segments as 0. */
+function compareVersions(a, b) {
+    const pa = a.split('.');
+    const pb = b.split('.');
+    const n = Math.max(pa.length, pb.length);
+    for (let i = 0; i < n; i++) {
+        const x = Number.parseInt(pa[i] ?? '0', 10) || 0;
+        const y = Number.parseInt(pb[i] ?? '0', 10) || 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/** A capability is supported iff it is known AND its `since` ≤ the host version. */
+function isSupportedCapability(cap, hostVersion = exports.REGISTRY_VERSION) {
+    if (!isKnownCapability(cap))
+        return false;
+    return compareVersions(exports.CAPABILITIES[cap].since, hostVersion) <= 0;
+}
+/**
+ * The subset of `caps` this host cannot enforce — unknown to its vocabulary, or
+ * declared at a `since` newer than `hostVersion`. A non-empty result means the
+ * region must refuse to mount with "update immediately.run (missing: …)" (T26).
+ * `hostVersion` is injectable so an older host can be simulated in tests.
+ */
+function unsupportedCapabilities(caps, hostVersion = exports.REGISTRY_VERSION) {
+    return caps.filter((c) => !isSupportedCapability(c, hostVersion));
+}

package/dist/docLayout.d.ts

@@ -0,0 +1,57 @@
+import type { CreateSpaceParams, GrantSpaceParams, NetFetchHost } from './port';
+/** A Firestore document path as alternating collection/doc segments, e.g.
+ *  `['user-app-spaces', uid, 'apps', appKey, 'spaces', spaceId]`. */
+export type DocPath = string[];
+/** The environment-specific Firestore sentinels the field builders inject. The
+ *  Web SDK passes `{ serverTimestamp, increment }` from `firebase/firestore`; the
+ *  admin SDK passes the `FieldValue.*` equivalents. */
+export interface MintSentinels {
+    serverTimestamp(): unknown;
+    increment(n: number): unknown;
+}
+/** 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. */
+export declare const grantKey: (appKey: string, spaceId: string) => string;
+/** 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. */
+export declare const GRANT_EXPIRY_MS: number;
+/** A principal that can be granted access to a space. */
+export declare const userPrincipal: (uid: string) => string;
+/** Drop undefined values — Firestore rejects them. The two adapters historically
+ *  each had their own copy of this; sharing it keeps the "omit absent optionals"
+ *  rule identical on both sides. */
+export declare const defined: <T extends Record<string, unknown>>(obj: T) => T;
+export declare const spacePath: (spaceId: string) => DocPath;
+export declare const memberPath: (spaceId: string, principal: 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;
+export declare const userCountPath: (uid: string) => DocPath;
+export declare const appCountPath: (uid: string, appKey: string) => DocPath;
+/** `spaces/{spaceId}` — the root doc (written WITHOUT merge). */
+export declare const spaceDocFields: (params: Pick<CreateSpaceParams, "owner" | "name" | "createdInNamespace" | "createdInRepository">, s: MintSentinels) => Record<string, unknown>;
+/** `spaces/{spaceId}/members/{user:owner}` — the owner membership (no merge). */
+export declare const ownerMemberFields: (s: MintSentinels) => Record<string, unknown>;
+/** `user-spaces/{owner}/spaces/{spaceId}` — EFFECTIVE access (no merge). */
+export declare const ownerUserSpaceFields: (params: Pick<CreateSpaceParams, "owner" | "name">) => Record<string, unknown>;
+/** `space-counts/{uid}` — per-user owned counter (merge). */
+export declare const userCountFields: (s: MintSentinels) => Record<string, unknown>;
+/** `space-counts/{uid}/apps/{appKey}` — per-app created counter (merge). */
+export declare const appCountFields: (s: MintSentinels) => Record<string, unknown>;
+/** `user-app-spaces/{uid}/apps/{appKey}` — the enumerable app-key marker doc
+ *  touched when a grant is written (merge). */
+export declare const appKeyTouchFields: (s: MintSentinels) => Record<string, unknown>;
+/** `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>;
+/** 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[];
+/** `user-app-spaces/{uid}/apps/{appKey}` — the net:fetch host grant (merge).
+ *  `hadGrantedAt` is whether the doc already carried a `netFetchGrantedAt` (so the
+ *  grant time is stamped ONCE, on first mint, and `netFetchLastUsedAt` refreshes
+ *  on every (re-)consent). */
+export declare const netFetchGrantFields: (mergedHosts: readonly NetFetchHost[], hadGrantedAt: boolean, s: MintSentinels) => Record<string, unknown>;

package/dist/docLayout.js

@@ -0,0 +1,156 @@
+"use strict";
+// The byte-faithful document layout (UI_AS_APPS_SPEC §8.6/§8.7/§8.15) — the
+// SINGLE source of the Firestore paths and field objects every grant-mint write
+// produces. The browser `FirestoreSpaceStore` (Web SDK) and the backend
+// `AdminMintStore` (admin SDK) write against two different Firestore client APIs
+// and therefore cannot share *call* code — but they MUST write byte-identical
+// documents (same collection paths, same field names, same `grantKey` /
+// `mintPath` / expiry stamping). If they drift, grants minted by the
+// CLI/backend would not be the grants site-main's boot gate reads — a silent,
+// security-relevant failure.
+//
+// The guarantee: both adapters compute their paths and assemble their field
+// objects HERE, injecting only the environment-specific timestamp/increment
+// SENTINELS (Web `serverTimestamp()`/`increment()` vs admin
+// `FieldValue.serverTimestamp()`/`FieldValue.increment()`). The raw
+// `.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.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.userPrincipal = exports.GRANT_EXPIRY_MS = 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;
+/** 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. */
+exports.GRANT_EXPIRY_MS = 90 * 24 * 60 * 60 * 1000;
+/** A principal that can be granted access to a space. */
+const userPrincipal = (uid) => `user:${uid}`;
+exports.userPrincipal = userPrincipal;
+/** Drop undefined values — Firestore rejects them. The two adapters historically
+ *  each had their own copy of this; sharing it keeps the "omit absent optionals"
+ *  rule identical on both sides. */
+const defined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+exports.defined = defined;
+// --- document paths (pure, sentinel-free) -----------------------------------
+const spacePath = (spaceId) => ['spaces', spaceId];
+exports.spacePath = spacePath;
+const memberPath = (spaceId, principal) => [
+    'spaces',
+    spaceId,
+    'members',
+    principal,
+];
+exports.memberPath = memberPath;
+const userSpacePath = (uid, spaceId) => [
+    'user-spaces',
+    uid,
+    'spaces',
+    spaceId,
+];
+exports.userSpacePath = userSpacePath;
+const appKeyPath = (uid, appKey) => [
+    'user-app-spaces',
+    uid,
+    'apps',
+    appKey,
+];
+exports.appKeyPath = appKeyPath;
+const appSpacePath = (uid, appKey, spaceId) => [
+    'user-app-spaces',
+    uid,
+    'apps',
+    appKey,
+    'spaces',
+    spaceId,
+];
+exports.appSpacePath = appSpacePath;
+const userCountPath = (uid) => ['space-counts', uid];
+exports.userCountPath = userCountPath;
+const appCountPath = (uid, appKey) => [
+    'space-counts',
+    uid,
+    'apps',
+    appKey,
+];
+exports.appCountPath = appCountPath;
+// --- field objects (inject the timestamp/increment sentinels) ---------------
+/** `spaces/{spaceId}` — the root doc (written WITHOUT merge). */
+const spaceDocFields = (params, s) => (0, exports.defined)({
+    owner: params.owner,
+    createdAt: s.serverTimestamp(),
+    name: params.name,
+    createdInNamespace: params.createdInNamespace,
+    createdInRepository: params.createdInRepository,
+});
+exports.spaceDocFields = spaceDocFields;
+/** `spaces/{spaceId}/members/{user:owner}` — the owner membership (no merge). */
+const ownerMemberFields = (s) => ({
+    role: 'owner',
+    addedAt: s.serverTimestamp(),
+});
+exports.ownerMemberFields = ownerMemberFields;
+/** `user-spaces/{owner}/spaces/{spaceId}` — EFFECTIVE access (no merge). */
+const ownerUserSpaceFields = (params) => (0, exports.defined)({ role: 'owner', name: params.name, owner: params.owner });
+exports.ownerUserSpaceFields = ownerUserSpaceFields;
+/** `space-counts/{uid}` — per-user owned counter (merge). */
+const userCountFields = (s) => ({
+    owned: s.increment(1),
+});
+exports.userCountFields = userCountFields;
+/** `space-counts/{uid}/apps/{appKey}` — per-app created counter (merge). */
+const appCountFields = (s) => ({
+    created: s.increment(1),
+});
+exports.appCountFields = appCountFields;
+/** `user-app-spaces/{uid}/apps/{appKey}` — the enumerable app-key marker doc
+ *  touched when a grant is written (merge). */
+const appKeyTouchFields = (s) => ({
+    touchedAt: s.serverTimestamp(),
+});
+exports.appKeyTouchFields = appKeyTouchFields;
+/** `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. */
+const appSpaceGrantFields = (params, s) => (0, exports.defined)({
+    boundAt: s.serverTimestamp(),
+    grantedAt: s.serverTimestamp(),
+    lastUsedAt: s.serverTimestamp(),
+    name: params.name,
+    // Plan 12 §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
+    // single-scope mint path still emits `rules` (byte-identical with site-main).
+    subtree: params.subtree,
+    mode: params.mode,
+    rules: params.rules && params.rules.length > 0
+        ? params.rules
+        : [{ subtree: params.subtree ?? '/', mode: params.mode ?? 'rw' }],
+    declaredUri: params.declaredUri,
+    mintPath: params.mintPath ?? 'interactive',
+    parentGrantId: params.parentGrantId,
+});
+exports.appSpaceGrantFields = appSpaceGrantFields;
+/** Union net:fetch host rules by origin (incoming wins) — the "consent
+ *  accumulates" merge both adapters apply before writing the host set. */
+const mergeNetFetchHosts = (existing, incoming) => {
+    const byOrigin = new Map();
+    for (const h of existing)
+        byOrigin.set(h.origin, h);
+    for (const h of incoming)
+        byOrigin.set(h.origin, h);
+    return [...byOrigin.values()];
+};
+exports.mergeNetFetchHosts = mergeNetFetchHosts;
+/** `user-app-spaces/{uid}/apps/{appKey}` — the net:fetch host grant (merge).
+ *  `hadGrantedAt` is whether the doc already carried a `netFetchGrantedAt` (so the
+ *  grant time is stamped ONCE, on first mint, and `netFetchLastUsedAt` refreshes
+ *  on every (re-)consent). */
+const netFetchGrantFields = (mergedHosts, hadGrantedAt, s) => (0, exports.defined)({
+    netFetch: [...mergedHosts],
+    netFetchGrantedAt: hadGrantedAt ? undefined : s.serverTimestamp(),
+    netFetchLastUsedAt: s.serverTimestamp(),
+});
+exports.netFetchGrantFields = netFetchGrantFields;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './capabilities';
+export * from './port';
+export * from './docLayout';
+export * from './bootConsent';
+export * from './m1PreAuth';

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+// @immediately-run/preauth-core — the shared pre-auth core.
+//
+// ONE §8.9 gate (`planPreAuthCapabilities`), ONE mint path (`mintConsentedGrants`,
+// `applyPreAuth`), ONE capability vocabulary (`./capabilities`), ONE wire layout
+// (`./docLayout`). site-main (browser Firestore) and the backend (admin Firestore)
+// both consume this so a CLI/backend-minted grant is byte-identical to one
+// site-main mints, and no surface can mint a capability the in-browser gate would
+// have refused.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./capabilities"), exports);
+__exportStar(require("./port"), exports);
+__exportStar(require("./docLayout"), exports);
+__exportStar(require("./bootConsent"), exports);
+__exportStar(require("./m1PreAuth"), exports);

package/dist/m1PreAuth.d.ts

@@ -0,0 +1,56 @@
+import { type Capability } from './capabilities';
+import { type ConsentSelection, type MintErrorSink, type MintResult } from './bootConsent';
+import type { MintStore, NetFetchHost } from './port';
+export type PreAuthRefusalReason = 
+/** A non-app-scoped elevated cap — region-binding-only authority (§8.9). */
+'broad-elevated'
+/** Not in the closed capability vocabulary (§5.12) — fail-closed. */
+ | 'unknown';
+export interface PreAuthRefusal {
+    capability: string;
+    reason: PreAuthRefusalReason;
+}
+export interface PreAuthPlan {
+    /** App-scoped elevated caps a policy MAY pre-authorize for a URL-loaded appKey. */
+    grantable: Capability[];
+    /** Baseline caps requested — auto-held, no grant needed (dropped silently). */
+    baseline: Capability[];
+    /** Refused by the §8.9 target check — these block the whole pre-auth. */
+    refused: PreAuthRefusal[];
+}
+/**
+ * The pure §8.9 target check: partition requested capability names into
+ * {grantable app-scoped, baseline no-op, refused}. Order-independent; total.
+ */
+export declare function planPreAuthCapabilities(requested: readonly string[]): PreAuthPlan;
+/** Safe to apply iff the §8.9 check refused nothing (fail-closed, all-or-nothing). */
+export declare const isPreAuthClean: (plan: PreAuthPlan) => boolean;
+/** What a policy/settings surface asks M1 to pre-authorize for `(uid, appKey)` —
+ *  structurally the same shape M3's consent screen produces (the declared
+ *  `requests`), so the two paths mint identical grants. */
+export interface PreAuthRequest {
+    /** Capability names being pre-authorized — validated by the §8.9 target check. */
+    capabilities: readonly string[];
+    /** Mount selections (create/bind a space per slot), mirroring the M3 screen. */
+    mounts: readonly ConsentSelection[];
+    /** net:fetch hosts to pre-grant (the headless/BYOK case). */
+    netFetchHosts: readonly NetFetchHost[];
+}
+export interface PreAuthResult {
+    /** True iff the pre-auth passed the §8.9 check AND every grant minted. */
+    ok: boolean;
+    /** §8.9 refusals — non-empty ⇒ NOTHING was minted (all-or-nothing). */
+    refused: PreAuthRefusal[];
+    /** The mint outcome, when the §8.9 check passed (absent on refusal). */
+    mint?: MintResult;
+}
+/**
+ * The M1 write path: validate the requested capabilities against the §8.9 target
+ * check, then — only if clean — mint the mounts + net:fetch hosts as durable
+ * grants with `policy` provenance, through the same `mintConsentedGrants` M3 uses.
+ *
+ * Refusal is terminal and silent of side effects: when any requested capability
+ * is broad-elevated or unknown, the function mints NOTHING and returns the
+ * refusals — the caller surfaces them (the policy is malformed/over-broad).
+ */
+export declare function applyPreAuth(store: MintStore, uid: string, appKey: string, request: PreAuthRequest, onError?: MintErrorSink): Promise<PreAuthResult>;

package/dist/m1PreAuth.js

@@ -0,0 +1,80 @@
+"use strict";
+// M1 — programmatic / policy pre-authorization (UI_AS_APPS_SPEC §8.15 "M1 —
+// Pre-authorization / policy", clamped by the §8.9 target check).
+//
+// M1 lets a policy (operator-tier) or settings (user-tier) write path record the
+// SAME durable consent-grant M3 writes — ahead of time, instead of at a modal —
+// so a headless/CI/cron/`immediately-run dev` run finds the grant already present
+// and boots with NO prompt. It is not a region-repointing registry layer (§3.3):
+// it only writes the §8.6/§8.7 grant set the gate already reads, so M1 minting
+// flows through the ONE existing mint path (`mintConsentedGrants`, stamped
+// `mintPath:'policy'`) and cannot drift from M3.
+//
+// THE SECURITY INVARIANT — the §8.9 target check. A pre-auth for a URL-loaded
+// `appKey` may only cover **app-scoped** elevated capabilities (`net:fetch`,
+// `task:invoke`, `contribute:self` — the set an ordinary previewed/forked app can
+// EARN per §8.9/§8.15) plus mounts (app-scoped by construction). A **broad-elevated**
+// capability — any non-app-scoped elevated cap (`spaces:user`/`spaces:admin`,
+// `editor:write`, `contribute:direct`/`contribute:any`, `editor:open`, …) — is
+// REFUSED: M1 cannot mint it for a URL-loaded appKey. Unknown capabilities are
+// refused (fail-closed). Baseline capabilities need no grant and are dropped.
+//
+// The check is **all-or-nothing**: if a policy names ANY refused capability the
+// whole pre-auth is rejected and NOTHING is minted — a partial apply would
+// silently drop the scary capability and look like it had been honored.
+//
+// Pure decision (`planPreAuthCapabilities`/`isPreAuthClean`) + a thin store-glue
+// write path (`applyPreAuth`) that reuses `mintConsentedGrants`. No React, no UI.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPreAuthClean = void 0;
+exports.planPreAuthCapabilities = planPreAuthCapabilities;
+exports.applyPreAuth = applyPreAuth;
+const capabilities_1 = require("./capabilities");
+const bootConsent_1 = require("./bootConsent");
+/**
+ * The pure §8.9 target check: partition requested capability names into
+ * {grantable app-scoped, baseline no-op, refused}. Order-independent; total.
+ */
+function planPreAuthCapabilities(requested) {
+    const grantable = [];
+    const baseline = [];
+    const refused = [];
+    for (const cap of requested) {
+        if (!(0, capabilities_1.isKnownCapability)(cap)) {
+            refused.push({ capability: cap, reason: 'unknown' });
+            continue;
+        }
+        if ((0, capabilities_1.isBaseline)(cap)) {
+            baseline.push(cap);
+            continue;
+        }
+        if ((0, capabilities_1.isAppScoped)(cap)) {
+            grantable.push(cap);
+            continue;
+        }
+        // Known + elevated + NOT app-scoped ⇒ broad-elevated: region-binding-only,
+        // never minted for a URL-loaded appKey (the §8.9 clamp).
+        refused.push({ capability: cap, reason: 'broad-elevated' });
+    }
+    return { grantable, baseline, refused };
+}
+/** Safe to apply iff the §8.9 check refused nothing (fail-closed, all-or-nothing). */
+const isPreAuthClean = (plan) => plan.refused.length === 0;
+exports.isPreAuthClean = isPreAuthClean;
+/**
+ * The M1 write path: validate the requested capabilities against the §8.9 target
+ * check, then — only if clean — mint the mounts + net:fetch hosts as durable
+ * grants with `policy` provenance, through the same `mintConsentedGrants` M3 uses.
+ *
+ * Refusal is terminal and silent of side effects: when any requested capability
+ * is broad-elevated or unknown, the function mints NOTHING and returns the
+ * refusals — the caller surfaces them (the policy is malformed/over-broad).
+ */
+async function applyPreAuth(store, uid, appKey, request, onError) {
+    const plan = planPreAuthCapabilities(request.capabilities);
+    if (!(0, exports.isPreAuthClean)(plan)) {
+        return { ok: false, refused: plan.refused };
+    }
+    const mint = await (0, bootConsent_1.mintConsentedGrants)(store, uid, appKey, request.mounts, request.netFetchHosts, 'policy', onError);
+    return { ok: mint.ok, refused: [], mint };
+}

package/dist/port.d.ts

@@ -0,0 +1,84 @@
+/** The filesystem scope a grant confers (UI_AS_APPS_SPEC §8.7). Absent fields
+ *  mean whole-space, read-write. */
+export type GrantMode = 'ro' | 'rw';
+/** One granted scope within a mount (UI_AS_APPS_SPEC §8.7, plan 12): an absolute
+ *  `subtree` in the backing fs and the access `mode` there. A grant carries a SET
+ *  of these (`rules`); the most specific (longest-prefix) rule governs a path. The
+ *  wire shape, so both mint adapters write byte-identical `rules` arrays. */
+export interface ScopeRule {
+    subtree: string;
+    mode: GrantMode;
+}
+/** How a durable grant was minted (UI_AS_APPS_SPEC §8.15 provenance). `interactive`
+ *  = the M3 consent screen; `policy` = M1 pre-authorization; `delegated` = M2
+ *  attenuated delegation from a parent grant. Drives the §8.11 audit view and, for
+ *  `delegated`, the revoke cascade (see `parentGrantId`). */
+export type MintPath = 'interactive' | 'policy' | 'delegated';
+/** A consented `net:fetch` host rule (§5.11) — structurally the registry's
+ *  `FetchRule`, redefined here so this backend-agnostic port stays import-free. */
+export interface NetFetchHost {
+    origin: string;
+    paths?: string[];
+    methods?: string[];
+    /** §8.15 provenance — how this host was granted (default `interactive`). For an
+     *  M2-`delegated` host this is the attenuated subset of a caller's net:fetch grant. */
+    mintPath?: MintPath;
+    /** §8.15 — for an M2 `delegated` host, the `netFetchGrantKey` of the caller's
+     *  net:fetch grant it was attenuated from; revoking that parent cascades here. */
+    parentGrantId?: string;
+}
+/** Parameters for `MintStore.createSpace` (named, `db`-free — the adapter holds
+ *  the connection). */
+export interface CreateSpaceParams {
+    owner: string;
+    name?: string;
+    /** Informational breadcrumbs only — never used for identity or access. */
+    createdInNamespace?: string;
+    createdInRepository?: string;
+    /** Record the new space in this app's binding list for the owner (the durable
+     *  app↔space link the grant scopes). No longer a slot pointer. */
+    appKey?: string;
+}
+/** Parameters for `MintStore.grantSpaceToApp` — the durable §8.7 grant for one
+ *  (app, mount): what the app may mount and how. */
+export interface GrantSpaceParams {
+    uid: string;
+    appKey: string;
+    spaceId: string;
+    subtree?: string;
+    mode?: GrantMode;
+    /** Plan 12 §8.7: the FULL rule-set to write (≥1). When given it is authoritative
+     *  (site-main's read-modify-merge passes the merged set); when omitted the grant
+     *  doc derives a single-rule `[{ subtree ?? '/', mode ?? 'rw' }]` from the legacy
+     *  `subtree`/`mode` (the backend single-scope path), so both adapters emit `rules`. */
+    rules?: ScopeRule[];
+    name?: string;
+    /** §11.4 — the declared required-mount uri this grant satisfies, so a later
+     *  boot re-provisions it without re-consent (the durable slot replacement). */
+    declaredUri?: string;
+    /** §8.15 provenance; defaults to `interactive` when omitted. */
+    mintPath?: MintPath;
+    /** §8.15 — parent `grantKey` for an M2 `delegated` grant. */
+    parentGrantId?: string;
+}
+/** Parameters for `MintStore.grantNetFetchHosts` — the per-(user, app) granted
+ *  host set, the grant half of the `manifest ∩ grant` net:fetch allowlist. */
+export interface GrantNetFetchParams {
+    uid: string;
+    appKey: string;
+    hosts: readonly NetFetchHost[];
+}
+/**
+ * The mint port: exactly the methods `mintConsentedGrants` calls. Every backend
+ * (browser Firestore, admin Firestore, the in-memory test double) implements
+ * these three the SAME way — serializing through the shared `docLayout` builders
+ * so the documents are byte-identical regardless of which SDK wrote them.
+ */
+export interface MintStore {
+    /** Create a new space owned by `owner`, returning its opaque generated id. */
+    createSpace(params: CreateSpaceParams): Promise<string>;
+    /** Record the durable §8.7 grant binding `spaceId` to `appKey` for `uid`. */
+    grantSpaceToApp(params: GrantSpaceParams): Promise<void>;
+    /** Union the given net:fetch hosts into the app's consented host set. */
+    grantNetFetchHosts(params: GrantNetFetchParams): Promise<void>;
+}

package/dist/port.js

@@ -0,0 +1,13 @@
+"use strict";
+// The mint PORT — the narrow persistence interface the ONE grant-mint path
+// (`mintConsentedGrants`) depends on, plus the shared domain types its params
+// carry. Both site-main's `FirestoreSpaceStore` (Firebase Web SDK) and the
+// backend's `AdminMintStore` (firebase-admin) structurally satisfy `MintStore`,
+// so the same orchestration drives both environments.
+//
+// This is a deliberate 3-method SUBSET of site-main's ~30-method `SpaceStore`:
+// `mintConsentedGrants` only ever calls `grantNetFetchHosts`, `createSpace`, and
+// `grantSpaceToApp` (the binding/grant doc IS the binding now — there is no
+// separate `bindSpaceToApp` slot write). The broad `SpaceStore` (subscriptions,
+// sharing, soft-delete, audit reads, …) stays in site-main and is NOT extracted.
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@immediately-run/preauth-core",
+  "version": "0.1.0",
+  "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",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./capabilities": {
+      "types": "./dist/capabilities.d.ts",
+      "default": "./dist/capabilities.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest",
+    "lint": "eslint src test",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.0",
+    "eslint": "^9.18.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.20.0"
+  }
+}