@immediately-run/preauth-core 0.1.2 → 0.1.3

package/dist/capabilities.d.ts

@@ -13,7 +13,10 @@ export interface CapabilityDef {
      *  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`,
+     *  (region binding only). In core_concepts §5 terms the consent-path is the
+     *  "above-the-floor, up-to-the-ceiling → first-use consent" band: an app-scoped
+     *  elevated cap sits in that band for the stage principal, a non-app-scoped one
+     *  is above the stage ceiling (granted only by a slot's elevated principal). The app-scoped set is `net:fetch`, `task:invoke`,
      *  `contribute:self` (decision #1 — its baseline→elevated reclassification landed
      *  in R3-33d), and `diagnostics:read` (R3-74 / P3-72, D4); the durable grant
      *  participates in the §8.15 90-day expiry like any app-scoped grant. */
@@ -22,8 +25,9 @@ export interface CapabilityDef {
      *  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). */
+     *  Independent of tier — it governs HOW the first-use consent line (core_concepts
+     *  §5: the above-floor consent band) is shown, not WHO may hold the capability
+     *  (a first-party-only cap is still refused to a fork regardless of styling). */
     maximallyExplicit?: boolean;
 }
 export declare const CAPABILITIES: Record<Capability, CapabilityDef>;
@@ -31,7 +35,7 @@ export declare const CAPABILITIES: Record<Capability, CapabilityDef>;
  *  provider-agnostic `llm:chat` capability (the `llm.chat@1` slot), mirroring
  *  capabilities.json. (1.2.0 added the per-user settings-space capabilities.) */
 export declare const REGISTRY_VERSION = "1.3.0";
-/** Is `cap` a known kernel capability? (Closed vocabulary — §5.12.) */
+/** Is `cap` a known host-core 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. */

package/dist/capabilities.js

@@ -1,6 +1,7 @@
 "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
+// The capability-definition registry — the Host-core source of truth
+// (UI_AS_APPS_SPEC §5.11 / §8.2). "Host-core capabilities are a closed,
+// kernel-defined vocabulary an app cannot extend" (core_concepts §5): apps
 // cannot mint one, only be granted one. This module mirrors docs/capabilities.json
 // (the machine-readable companion); the host build is authoritative.
 //
@@ -61,7 +62,7 @@ exports.CAPABILITIES = {
     // 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
+    // (and notifies Sandpack) — the COW/journal stays in the Host (§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
@@ -128,9 +129,12 @@ exports.CAPABILITIES = {
     // / 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`).
+    // first-party line that carries it renders with the scariest styling. (Tier is
+    // `first-party-only`, the SAME tier as `vcs:reset` — NOT `editor:write`, which is
+    // elevated/consentable: S4 in spec-review-3.5 corrected the FILE_EXPLORER prose
+    // that wrongly equated this tier with `editor:write`. CAPABILITY_REFERENCE records
+    // `dnd:source` as first-party-only, which this dict matches.) 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
@@ -154,8 +158,8 @@ exports.CAPABILITIES = {
     'secrets:list': { kind: 'read', tier: 'elevated', since: '1.1.0' },
     'secrets:revoke': { kind: 'action', tier: 'elevated', since: '1.1.0' },
     // R3-76 (P3-74, LLM_AND_AGENTS_SPEC §3.4/§4; LOCAL_DEV_AUTHED_SERVER_SPEC):
-    // open and drive a user-local Claude Code via the bridge — the in-browser host
-    // kernel connects OUT to the CLI's authenticated localhost server and runs each
+    // open and drive a user-local Claude Code via the bridge — the in-browser Host
+    // connects OUT to the CLI's authenticated localhost server and runs each
     // tool call through its §8.4-gated invoke(). Promoted from proposed/since:null
     // to a defined, gated, elevated capability landing in the current 1.2.0
     // registry — gated host-side by `protocol-agent` (site-main actionGate) and held
@@ -171,7 +175,10 @@ exports.CAPABILITIES = {
     // diagnostics (no cross-app bleed — enforced host-side by the channel projection).
     'diagnostics:read': { kind: 'action', tier: 'elevated', since: '1.2.0', appScoped: true },
     // SERVICE_PROVIDERS_SPEC `llm.chat@1` / LLM_AND_AGENTS_SPEC D5: invoke the shared,
-    // provider-agnostic chat slot. The app calls ONE slot; the host resolves which
+    // provider-agnostic chat slot. ("provider" here = the Service-provider sense —
+    // an App that provides a Service, core_concepts §6 — and "slot" here = a Service
+    // interface, not the UI Slot of core_concepts §3; the names mirror the
+    // SERVICE_PROVIDERS surface and are kept.) The app calls ONE slot; the host resolves which
     // vendor answers from the key the user holds (`SecretView.boundOrigin`) + their
     // `preferredImplementation` choice, injects the key host-side (§6, look-at-nothing
     // proxy), and streams normalized deltas back. The app never names a vendor, never
@@ -184,7 +191,7 @@ exports.CAPABILITIES = {
  *  provider-agnostic `llm:chat` capability (the `llm.chat@1` slot), mirroring
  *  capabilities.json. (1.2.0 added the per-user settings-space capabilities.) */
 exports.REGISTRY_VERSION = '1.3.0';
-/** Is `cap` a known kernel capability? (Closed vocabulary — §5.12.) */
+/** Is `cap` a known host-core capability? (Closed vocabulary — §5.12.) */
 function isKnownCapability(cap) {
     return Object.prototype.hasOwnProperty.call(exports.CAPABILITIES, cap);
 }

package/dist/docLayout.d.ts

@@ -17,14 +17,22 @@ export declare const grantKey: (appKey: string, spaceId: string) => string;
  *  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. */
+/** The member doc-ID for a user who can be granted access to a space: `user:<uid>`.
+ *  This is a **grantee** (a space member — the `uid`/`gid` of `setSpaceRole`), NOT the
+ *  authority-context Principal (core_concepts §4 reserved-word; SPEC_CODE_DEBT §7.1
+ *  RENAME-1). The stored Firestore path segment is a doc-ID, not a field literally
+ *  named `principal`, so this rename is code-symbol-only — no data migration. */
+export declare const granteeId: (uid: string) => string;
+/** @deprecated use {@link granteeId}. Kept as an alias for the `userPrincipal →
+ *  granteeId` migration (the SDK + site-main + backend RENAME-1 track); removed once
+ *  consumers migrate. */
 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 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;

package/dist/docLayout.js

@@ -16,7 +16,7 @@
 // `.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;
+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.granteeId = 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. */
@@ -26,9 +26,17 @@ exports.grantKey = grantKey;
  *  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;
+/** The member doc-ID for a user who can be granted access to a space: `user:<uid>`.
+ *  This is a **grantee** (a space member — the `uid`/`gid` of `setSpaceRole`), NOT the
+ *  authority-context Principal (core_concepts §4 reserved-word; SPEC_CODE_DEBT §7.1
+ *  RENAME-1). The stored Firestore path segment is a doc-ID, not a field literally
+ *  named `principal`, so this rename is code-symbol-only — no data migration. */
+const granteeId = (uid) => `user:${uid}`;
+exports.granteeId = granteeId;
+/** @deprecated use {@link granteeId}. Kept as an alias for the `userPrincipal →
+ *  granteeId` migration (the SDK + site-main + backend RENAME-1 track); removed once
+ *  consumers migrate. */
+exports.userPrincipal = exports.granteeId;
 /** 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. */
@@ -37,11 +45,11 @@ exports.defined = defined;
 // --- document paths (pure, sentinel-free) -----------------------------------
 const spacePath = (spaceId) => ['spaces', spaceId];
 exports.spacePath = spacePath;
-const memberPath = (spaceId, principal) => [
+const memberPath = (spaceId, grantee) => [
     'spaces',
     spaceId,
     'members',
-    principal,
+    grantee,
 ];
 exports.memberPath = memberPath;
 const userSpacePath = (uid, spaceId) => [
@@ -119,7 +127,7 @@ const appSpaceGrantFields = (params, s) => (0, exports.defined)({
     grantedAt: s.serverTimestamp(),
     lastUsedAt: s.serverTimestamp(),
     name: params.name,
-    // Plan 12 §8.7: `rules` is authoritative; `subtree`/`mode` are kept as the
+    // 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
     // single-scope mint path still emits `rules` (byte-identical with site-main).

package/dist/m1PreAuth.js

@@ -7,6 +7,12 @@
 // 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
+//
+// ("region-binding-only" below = the UI half of a Slot (core_concepts §3): the
+// Slot's principal confers such a capability as part of being bound, NOT via a
+// consent path (slot occupancy is not a capability, core_concepts §3/§5) — which
+// is exactly why a URL-loaded appKey, which CANNOT pick its slot, can never EARN a
+// broad-elevated cap, only the app-scoped consent-path caps below.)
 // flows through the ONE existing mint path (`mintConsentedGrants`, stamped
 // `mintPath:'policy'`) and cannot drift from M3.
 //

package/dist/port.d.ts

@@ -1,7 +1,7 @@
 /** 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
+/** One granted scope within a mount (UI_AS_APPS_SPEC §8.7): 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. */
@@ -47,7 +47,7 @@ export interface GrantSpaceParams {
     spaceId: string;
     subtree?: string;
     mode?: GrantMode;
-    /** Plan 12 §8.7: the FULL rule-set to write (≥1). When given it is authoritative
+    /** UI_AS_APPS_SPEC §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`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/preauth-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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": {