@vantageos/cloud-identity 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,71 @@
 All notable changes to `@vantageos/cloud-identity` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0]
+
+**Additive — grant-aware scope filter.** Closes the other pole of the
+fail-closed defect class: 0.3.0/0.4.0 closed "a right granted by ABSENCE"
+(missing `oauthCtx` silently passing everything); this closes "a right
+REFUSED by absence" — a per-row grant (a named mission agent/pilot, a
+mandate's `fulfilledBy`) that IS present on the row but that
+`passesScopeFilter`/`scopeFilterList`/`scopeFilterGet` were structurally
+blind to, because they only ever consulted `createdBy`/`namespace`.
+
+### Added
+
+- `passesScopeFilter`, `scopeFilterList`, `scopeFilterGet` (`src/scope-filter.ts`)
+  now accept an optional `grantFields: readonly string[]` parameter, defaulting
+  to `[]`. Each entry names a property on the row that the CALLER declares as
+  a per-row grant — the field's runtime value is treated as a single identity
+  (`string`, equality match) or multiple identities (`string[]`, any-element
+  match) against `oauthCtx.fromAllowList`. The package never hardcodes which
+  fields are grants for which table; that declaration is caller-supplied data.
+- **Fail-closed regression preserved byte-for-byte:** omitting `grantFields`
+  (or passing `[]`) reproduces 0.4.0 behaviour exactly — this is a pure
+  widening, no existing caller's behaviour changes without an explicit
+  opt-in declaration at its own call site.
+
+## [0.4.0]
+
+**Additive.** Two new primitives so one identity layer covers both deployment
+shapes and the human sign-in path — no separate self-host layer, no change to
+the Cloud/machine path. Serves Tau's `vantage-starter` self-host install and
+the Hephaistos human-path onboarding, both stalled on this surface.
+
+### Added
+
+- **Named deployment mode** — `DeploymentMode` (`"cloud" | "self-host"`) and a
+  `{ kind: "self-host"; tenantId }` branch on `TenantSource` / `requireTenantId`
+  (`src/org-guard.ts`). `cloud` keeps the existing fail-closed behaviour
+  unchanged (org/workspace required on every request — invariant #1123 holds,
+  0.4.0 reopens nothing). `self-host` is single-tenant: `requireTenantId`
+  returns the configured `tenantId` only when it is a non-empty string, and
+  **throws** otherwise — the tenant is presented explicitly by configuration,
+  never inferred from the absence of an organization.
+- **Human-path resolver** — `normalizeVerifiedHumanSession()` (`src/human-path.ts`,
+  new `./human-path` subpath export) maps an already-*verified*, framework-agnostic
+  Clerk-shaped session (`{ orgId, userId, orgRole }`) to
+  `{ tenant, subject, role }`. `role` is a new union `HumanAccountRole`
+  (`owner | admin | member | client`), distinct from `workspaceRoleSchema`
+  (`Admin | Editor | Viewer`) and never conflated. No Clerk SDK is imported.
+  Refuses (throws) on no session, no org, no user id, or an unrecognized/absent
+  org role — presented, never inferred. **Naming fix, still pre-publish:** this
+  function was originally named `resolveHumanIdentity`, which invited passing
+  in an unverified, client-supplied object (e.g. `req.body`) and would make
+  that object the trusted source of tenant/subject/role — a
+  privilege-escalation risk. Renamed to `normalizeVerifiedHumanSession` before
+  0.4.0 reaches npm (current published latest is 0.3.0) to make the
+  already-verified precondition explicit at the call-site, mirroring
+  `decodeUnverifiedBearer`'s rename from `resolveBearer` in 0.2.0. Not a
+  breaking change — 0.4.0 has no npm consumer yet.
+
+### Notes
+
+- Purely additive: every 0.3.0 export (`passesScopeFilter`, `scopeFilterList`,
+  `scopeFilterGet`, `validateMasterBearer`, `getEffectiveTenantId`,
+  `decodeUnverifiedBearer`, `requireTenantId`'s `session`/`bearer` branches, …)
+  is behaviorally unchanged. Full suite 87/87, `tsc --noEmit` 0.
+
 ## [Unreleased] - 0.3.0
 
 **BREAKING.** Closes two measured 0.2.0 defects — a right must never be

package/README.md

@@ -153,7 +153,64 @@ want to catch by type, and `BearerPayload`, the type returned by
 - `SessionIdentity` — the human-path shape `requireTenantId` accepts under
   `{ kind: "session", identity }` (see "Both caller paths, one contract").
 - `TenantSource` — the discriminated union `requireTenantId` accepts:
-  `{ kind: "session", identity }` or `{ kind: "bearer", context }`.
+  `{ kind: "session", identity }`, `{ kind: "bearer", context }`, or
+  `{ kind: "self-host", tenantId }`.
+- `DeploymentMode` — the named `"cloud" | "self-host"` literal union (0.4.0).
+
+**Deployment mode and the human path (0.4.0, additive)**
+
+- `DeploymentMode` (`"cloud" | "self-host"`) names the two ways this package
+  can be run. `cloud` keeps `requireTenantId`'s existing session/bearer
+  behaviour exactly as-is — organization/workspace REQUIRED, fail-closed.
+  `self-host` is single-tenant: pass `{ kind: "self-host", tenantId }` to
+  `requireTenantId`, and it returns `tenantId` when it is a non-empty string.
+  The self-host tenant id must be DECLARED via configuration — if you select
+  self-host mode without configuring a tenant id, `requireTenantId` throws
+  rather than returning a default. A right is never granted by absence,
+  whichever mode you are in.
+
+  ```ts
+  import { requireTenantId } from "@vantageos/cloud-identity";
+
+  // self-host: the tenant id is configured explicitly, once, at startup.
+  requireTenantId({ kind: "self-host", tenantId: "the-one-tenant" });
+  // -> "the-one-tenant"
+
+  requireTenantId({ kind: "self-host", tenantId: undefined });
+  // -> throws: "No tenant id configured for self-host mode..."
+  ```
+
+- `normalizeVerifiedHumanSession(session)` — **normalizes, does not
+  authenticate.** Maps an already-*verified* (not merely well-shaped),
+  framework-agnostic Clerk session object (`{ orgId, userId, orgRole }`) to
+  `{ tenant, subject, role }`. This package never imports a Clerk SDK; the
+  caller MUST verify the session upstream (e.g. Clerk's server-side `auth()`)
+  and pass in the already-verified object — never an unverified,
+  client-supplied object such as `req.body`, which would make the caller's
+  input the trusted source of tenant/subject/role. Refuses (throws) when the
+  session has no organization, no user id, or an org role this package does
+  not recognize — never defaults silently; these are shape checks, not a
+  verification step.
+- `humanAccountRoleSchema` (type `HumanAccountRole`) — the new
+  `"owner" | "admin" | "member" | "client"` role union returned by
+  `normalizeVerifiedHumanSession`. Distinct from `workspaceRoleSchema`
+  (`Admin | Editor | Viewer`) — one is an organization-account role, the
+  other is workspace membership; they are never conflated.
+- `ClerkSessionLike` — the minimal input shape `normalizeVerifiedHumanSession` accepts:
+  `{ orgId?, userId?, orgRole? }`.
+- `ResolvedHumanIdentity` — the `{ tenant, subject, role }` return type of
+  `normalizeVerifiedHumanSession`.
+
+  ```ts
+  import { normalizeVerifiedHumanSession } from "@vantageos/cloud-identity";
+
+  normalizeVerifiedHumanSession({
+    orgId: "org_abc",
+    userId: "user_123",
+    orgRole: "org:admin",
+  });
+  // -> { tenant: "org_abc", subject: "user_123", role: "admin" }
+  ```
 
 ## What this package does not do
 
@@ -172,6 +229,49 @@ Worth reading before you rely on it.
   have already fetched. If fetching them was itself expensive or unsafe, filter
   earlier, in your query.
 
+## Upgrading to 0.4.0
+
+**This release is purely additive — nothing you already call changes.** Every
+0.3.0 export keeps its exact behaviour; 0.4.0 only adds two primitives, so an
+upgrade from 0.3.0 compiles and runs unchanged until you choose to adopt them.
+
+What is new:
+
+- **A named deployment mode.** `requireTenantId` gains a `self-host` source
+  alongside `session` and `bearer`. `cloud` is unchanged — an org-less
+  identity is still refused. `self-host` is single-tenant and returns the
+  tenant you **declare**; it throws when none is configured, never inferring
+  one from absence.
+
+  ```js
+  import { requireTenantId } from "@vantageos/cloud-identity";
+
+  // cloud (unchanged): refuses when the session has no org
+  requireTenantId({ kind: "session", identity });
+  // self-host: returns the DECLARED tenant, throws if it is empty
+  requireTenantId({ kind: "self-host", tenantId: process.env.TENANT_ID });
+  ```
+
+- **A human-path normalizer.** `normalizeVerifiedHumanSession` maps an
+  **already-verified** Clerk-shaped session into `{ tenant, subject, role }`
+  (`role` ∈ `owner | admin | member | client`).
+
+  ```js
+  import { normalizeVerifiedHumanSession } from "@vantageos/cloud-identity";
+
+  // session MUST already be verified upstream, e.g. Clerk auth() server-side:
+  const { tenant, subject, role } = normalizeVerifiedHumanSession(session);
+  ```
+
+  ⚠️ It **normalizes, it does not authenticate.** Passing an unverified,
+  client-controlled object (a `req.body`, a query payload) makes that object
+  the trusted source of tenant, subject and role — a privilege escalation.
+  Verify the session upstream first; only pass the object your provider
+  already verified. (Same discipline as `decodeUnverifiedBearer`.)
+
+Nothing to change on upgrade, nothing removed. Adopt the new primitives when
+you need them.
+
 ## Upgrading to 0.3.0
 
 **This release changes a default, and it breaks compilation on purpose.**

package/dist/human-path.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @vantageos/cloud-identity 0.4.0 — Human-path resolver (Clerk → { tenant,
+ * subject, role }).
+ *
+ * Additive-only: does not import any Clerk SDK, and does not modify any
+ * existing export. The caller resolves a Clerk session (or any session
+ * provider with an equivalent shape) *outside* this package and passes in a
+ * plain, already-resolved object; this module only normalizes it into the
+ * package's contract.
+ *
+ * `role` is a NEW literal union (`owner | admin | member | client`),
+ * distinct from `workspaceRoleSchema` (`Admin | Editor | Viewer`) in
+ * `./tenancy-domain.ts` — the two are unrelated vocabularies (workspace
+ * membership role vs. organization-account role) and are never conflated.
+ *
+ * Consistent with the package's "a right is presented, never inferred from
+ * an absence" contract: a session with no organization refuses (throws),
+ * and an unrecognized/absent Clerk org role refuses (throws) rather than
+ * silently defaulting to a role.
+ */
+import { z } from "zod";
+export declare const humanAccountRoleSchema: z.ZodEnum<{
+    owner: "owner";
+    admin: "admin";
+    member: "member";
+    client: "client";
+}>;
+export type HumanAccountRole = z.infer<typeof humanAccountRoleSchema>;
+/**
+ * The minimal shape this package needs out of an already-resolved Clerk
+ * session (e.g. the object returned by Clerk's own `auth()` in a Next.js
+ * server context). No Clerk SDK type is imported — this is a structural
+ * shape the caller supplies directly.
+ */
+export type ClerkSessionLike = {
+    orgId?: string | null;
+    userId?: string | null;
+    orgRole?: string | null;
+};
+export type ResolvedHumanIdentity = {
+    tenant: string;
+    subject: string;
+    role: HumanAccountRole;
+};
+/**
+ * @security ⚠️ DECODE/NORMALIZE-ONLY. NOT AUTHENTICATION. NOT VERIFICATION.
+ *
+ * This function does NOT authenticate a request and does NOT verify
+ * anything. It NORMALIZES a session that the caller has ALREADY verified
+ * upstream — e.g. via Clerk's own server-side `auth()` in a Next.js/Convex
+ * server context — into this package's `{ tenant, subject, role }` contract.
+ *
+ * Passing an unverified, client-supplied object here (for example
+ * `req.body`, a query-string payload, or anything else an attacker
+ * controls) makes THAT object the trusted source of `tenant`, `subject`,
+ * AND `role` — a privilege-escalation bug. The shape checks below (missing
+ * orgId/userId/orgRole) only guard against malformed input; they perform
+ * NO signature check, NO issuer check, NO session-validity check.
+ *
+ * Callers MUST verify the session upstream (Clerk `auth()` server-side, or
+ * an equivalent signed-session verifier) BEFORE calling this function. Only
+ * pass in the object Clerk itself already verified — never pass through an
+ * unverified request body.
+ *
+ * Resolves an already-verified, framework-agnostic Clerk session object into
+ * the package's `{ tenant, subject, role }` contract.
+ *
+ *   - throws when `session` is null/undefined ("Unauthenticated: no
+ *     session.") — same refusal message class as `requireTenantId`'s
+ *     session branch, for consistent error handling across both resolvers.
+ *   - throws when `session.orgId` is missing or empty ("No active
+ *     organization on this session...") — human path is cloud fail-closed,
+ *     same invariant as `requireTenantId`.
+ *   - throws when `session.userId` is missing or empty.
+ *   - throws when `session.orgRole` is missing, empty, or not a recognized
+ *     Clerk org role (unknown roles are refused, never defaulted).
+ *
+ * Named to make the already-verified precondition explicit at the
+ * call-site — see CHANGELOG.md 0.4.0 for the naming history — mirroring
+ * `decodeUnverifiedBearer`'s equivalent rename in `./tenancy-domain.ts`.
+ *
+ * @example
+ * ```ts
+ * // session MUST already be verified upstream, e.g.:
+ * // const { orgId, userId, orgRole } = await auth(); // Clerk server-side
+ * const { tenant, subject, role } = normalizeVerifiedHumanSession({
+ *   orgId: "org_abc",
+ *   userId: "user_123",
+ *   orgRole: "org:admin",
+ * });
+ * // -> { tenant: "org_abc", subject: "user_123", role: "admin" }
+ * ```
+ */
+export declare function normalizeVerifiedHumanSession(session: ClerkSessionLike | null | undefined): ResolvedHumanIdentity;
+//# sourceMappingURL=human-path.d.ts.map

package/dist/human-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-path.d.ts","sourceRoot":"","sources":["../src/human-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,sBAAsB;;;;;EAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAMtE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAMF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAoBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC3C,qBAAqB,CAiCvB"}

package/dist/human-path.js

@@ -0,0 +1,117 @@
+/**
+ * @vantageos/cloud-identity 0.4.0 — Human-path resolver (Clerk → { tenant,
+ * subject, role }).
+ *
+ * Additive-only: does not import any Clerk SDK, and does not modify any
+ * existing export. The caller resolves a Clerk session (or any session
+ * provider with an equivalent shape) *outside* this package and passes in a
+ * plain, already-resolved object; this module only normalizes it into the
+ * package's contract.
+ *
+ * `role` is a NEW literal union (`owner | admin | member | client`),
+ * distinct from `workspaceRoleSchema` (`Admin | Editor | Viewer`) in
+ * `./tenancy-domain.ts` — the two are unrelated vocabularies (workspace
+ * membership role vs. organization-account role) and are never conflated.
+ *
+ * Consistent with the package's "a right is presented, never inferred from
+ * an absence" contract: a session with no organization refuses (throws),
+ * and an unrecognized/absent Clerk org role refuses (throws) rather than
+ * silently defaulting to a role.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// HumanAccountRole
+// ---------------------------------------------------------------------------
+export const humanAccountRoleSchema = z.enum([
+    "owner",
+    "admin",
+    "member",
+    "client",
+]);
+/**
+ * Maps Clerk's own org-role strings (`org:admin`, `org:member`, etc. — and
+ * their bare forms `admin`, `member`) onto the package's `HumanAccountRole`
+ * union. Deliberately explicit and exhaustive-by-throw: any string not
+ * listed here is refused rather than silently coerced to a default, per
+ * "presented, never inferred from an absence."
+ */
+const CLERK_ORG_ROLE_MAP = {
+    "org:owner": "owner",
+    owner: "owner",
+    "org:admin": "admin",
+    admin: "admin",
+    "org:member": "member",
+    member: "member",
+    "org:client": "client",
+    client: "client",
+};
+/**
+ * @security ⚠️ DECODE/NORMALIZE-ONLY. NOT AUTHENTICATION. NOT VERIFICATION.
+ *
+ * This function does NOT authenticate a request and does NOT verify
+ * anything. It NORMALIZES a session that the caller has ALREADY verified
+ * upstream — e.g. via Clerk's own server-side `auth()` in a Next.js/Convex
+ * server context — into this package's `{ tenant, subject, role }` contract.
+ *
+ * Passing an unverified, client-supplied object here (for example
+ * `req.body`, a query-string payload, or anything else an attacker
+ * controls) makes THAT object the trusted source of `tenant`, `subject`,
+ * AND `role` — a privilege-escalation bug. The shape checks below (missing
+ * orgId/userId/orgRole) only guard against malformed input; they perform
+ * NO signature check, NO issuer check, NO session-validity check.
+ *
+ * Callers MUST verify the session upstream (Clerk `auth()` server-side, or
+ * an equivalent signed-session verifier) BEFORE calling this function. Only
+ * pass in the object Clerk itself already verified — never pass through an
+ * unverified request body.
+ *
+ * Resolves an already-verified, framework-agnostic Clerk session object into
+ * the package's `{ tenant, subject, role }` contract.
+ *
+ *   - throws when `session` is null/undefined ("Unauthenticated: no
+ *     session.") — same refusal message class as `requireTenantId`'s
+ *     session branch, for consistent error handling across both resolvers.
+ *   - throws when `session.orgId` is missing or empty ("No active
+ *     organization on this session...") — human path is cloud fail-closed,
+ *     same invariant as `requireTenantId`.
+ *   - throws when `session.userId` is missing or empty.
+ *   - throws when `session.orgRole` is missing, empty, or not a recognized
+ *     Clerk org role (unknown roles are refused, never defaulted).
+ *
+ * Named to make the already-verified precondition explicit at the
+ * call-site — see CHANGELOG.md 0.4.0 for the naming history — mirroring
+ * `decodeUnverifiedBearer`'s equivalent rename in `./tenancy-domain.ts`.
+ *
+ * @example
+ * ```ts
+ * // session MUST already be verified upstream, e.g.:
+ * // const { orgId, userId, orgRole } = await auth(); // Clerk server-side
+ * const { tenant, subject, role } = normalizeVerifiedHumanSession({
+ *   orgId: "org_abc",
+ *   userId: "user_123",
+ *   orgRole: "org:admin",
+ * });
+ * // -> { tenant: "org_abc", subject: "user_123", role: "admin" }
+ * ```
+ */
+export function normalizeVerifiedHumanSession(session) {
+    if (!session) {
+        throw new Error("Unauthenticated: no session.");
+    }
+    const { orgId, userId, orgRole } = session;
+    if (typeof orgId !== "string" || orgId.length === 0) {
+        throw new Error("No active organization on this session: select an organization before accessing agents.");
+    }
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new Error("No user id on this session: cannot resolve subject.");
+    }
+    if (typeof orgRole !== "string" || orgRole.length === 0) {
+        throw new Error("No organization role on this session: role must be presented explicitly, never inferred.");
+    }
+    const mapped = CLERK_ORG_ROLE_MAP[orgRole];
+    if (!mapped) {
+        throw new Error(`Unrecognized organization role "${orgRole}": expected one of ${Object.keys(CLERK_ORG_ROLE_MAP).join(", ")}.`);
+    }
+    return { tenant: orgId, subject: userId, role: mapped };
+}
+//# sourceMappingURL=human-path.js.map

package/dist/human-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-path.js","sourceRoot":"","sources":["../src/human-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC3C,OAAO;IACP,OAAO;IACP,QAAQ;IACR,QAAQ;CACT,CAAC,CAAC;AA6BH;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAqC;IAC3D,WAAW,EAAE,OAAO;IACpB,KAAK,EAAE,OAAO;IACd,WAAW,EAAE,OAAO;IACpB,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,QAAQ;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,UAAU,6BAA6B,CAC3C,OAA4C;IAE5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mCAAmC,OAAO,sBAAsB,MAAM,CAAC,IAAI,CACzE,kBAAkB,CACnB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAChB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -12,5 +12,7 @@ export type { OAuthCtx, ScopeProfile, NamespacePrefix, FromAllowListEntry, Valid
 export { workspaceSchema, workspaceMemberSchema, workspaceRoleSchema, tenantContextSchema, ScopeViolationError, getEffectiveTenantId, decodeUnverifiedBearer, } from "./tenancy-domain.js";
 export type { Workspace, WorkspaceMember, WorkspaceRole, TenantContext, ScopeViolationPayload, BearerPayload, } from "./tenancy-domain.js";
 export { requireTenantId } from "./org-guard.js";
-export type { SessionIdentity, TenantSource } from "./org-guard.js";
+export type { SessionIdentity, TenantSource, DeploymentMode, } from "./org-guard.js";
+export { humanAccountRoleSchema, normalizeVerifiedHumanSession } from "./human-path.js";
+export type { HumanAccountRole, ClerkSessionLike, ResolvedHumanIdentity, } from "./human-path.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACV,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -10,6 +10,8 @@ export { passesScopeFilter, scopeFilterList, scopeFilterGet, isMasterScope, isWi
 export { validateMasterBearer } from "./bearer-validation.js";
 // 0.2.0 — Domain-tenancy layer (additive)
 export { workspaceSchema, workspaceMemberSchema, workspaceRoleSchema, tenantContextSchema, ScopeViolationError, getEffectiveTenantId, decodeUnverifiedBearer, } from "./tenancy-domain.js";
-// Organization-membership guard (unified session + bearer contract)
+// Organization-membership guard (unified session + bearer + self-host contract)
 export { requireTenantId } from "./org-guard.js";
+// 0.4.0 — Human-path resolver (Clerk-shaped session -> { tenant, subject, role })
+export { humanAccountRoleSchema, normalizeVerifiedHumanSession } from "./human-path.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,GAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAS9D,0CAA0C;AAC1C,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAU7B,oEAAoE;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,GAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAS9D,0CAA0C;AAC1C,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAU7B,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAOjD,kFAAkF;AAClF,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/org-guard.d.ts

@@ -44,6 +44,15 @@ import type { TenantContext } from "./tenancy-domain.js";
 export type SessionIdentity = {
     orgId?: string | null;
 };
+/**
+ * Named deployment mode — 0.4.0. `cloud` requires an organization/workspace
+ * on every request (the existing, unchanged `session`/`bearer` behaviour
+ * below). `self-host` is single-tenant: the tenant id is DECLARED via
+ * explicit configuration, never inferred from the absence of an
+ * organization. See the `self-host` branch of `TenantSource` and
+ * `requireTenantId` for the refuse-on-missing-config semantics.
+ */
+export type DeploymentMode = "cloud" | "self-host";
 /**
  * Discriminated union covering both VantagePeers Cloud entry paths behind
  * one contract:
@@ -51,6 +60,10 @@ export type SessionIdentity = {
  *   - `bearer`: machine path, via a resolved, ALREADY-VERIFIED token
  *     (`TenantContext` — see `decodeUnverifiedBearer` / the planned signed-JWT
  *     verifier for how a `TenantContext` gets produced).
+ *   - `self-host`: single-tenant path (0.4.0, additive). The tenant id is
+ *     presented explicitly by configuration, not inferred: `requireTenantId`
+ *     returns `tenantId` only when it is a non-empty string, and throws
+ *     otherwise — a right is never granted by absence, here either.
  */
 export type TenantSource = {
     kind: "session";
@@ -58,6 +71,9 @@ export type TenantSource = {
 } | {
     kind: "bearer";
     context: TenantContext;
+} | {
+    kind: "self-host";
+    tenantId: string | null | undefined;
 };
 /**
  * Resolve the caller's tenant id, refusing when no organization/workspace is

package/dist/org-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"org-guard.d.ts","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAqB5D"}
+{"version":3,"file":"org-guard.d.ts","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,WAAW,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA+B5D"}

package/dist/org-guard.js

@@ -61,6 +61,13 @@ export function requireTenantId(source) {
         }
         return orgId;
     }
+    if (source.kind === "self-host") {
+        const tenantId = source.tenantId;
+        if (typeof tenantId !== "string" || tenantId.length === 0) {
+            throw new Error("No tenant id configured for self-host mode: declare a tenantId explicitly — it is never inferred from absence.");
+        }
+        return tenantId;
+    }
     const workspaceId = source.context?.workspaceId;
     if (typeof workspaceId !== "string" || workspaceId.length === 0) {
         throw new Error("No workspace on this bearer-resolved tenant context: the bearer must resolve to a non-empty workspaceId.");

package/dist/org-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"org-guard.js","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AA0BH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC;IAChD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}
+{"version":3,"file":"org-guard.js","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAyCH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,KAAK,CACb,gHAAgH,CACjH,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC;IAChD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/scope-filter.d.ts

@@ -5,6 +5,31 @@
  * implementation; the only change was replacing a framework-specific context
  * type with the framework-agnostic `OAuthCtx` from `./types`.
  *
+ * Contract (0.5.0 — additive, widening only, vs. 0.4.0):
+ *   - Every exported predicate/filter now accepts an OPTIONAL `grantFields`
+ *     parameter: `readonly string[]`, defaulting to `[]`. Each entry names a
+ *     property on the row that the CALLER declares as a per-row grant (e.g.
+ *     "agents", "pilot", "fulfilledBy"). The package never hardcodes which
+ *     fields are grants for which table — that declaration is data supplied
+ *     by the caller at the call site, not business knowledge baked into this
+ *     shared module (no-hardcoded-business-knowledge).
+ *   - A row passes for a non-master caller if createdBy/namespace already
+ *     passed (0.4.0 behaviour, unchanged) OR if ANY declared grant field's
+ *     value names an identity in `oauthCtx.fromAllowList` — the field may be
+ *     a single string (e.g. "pilot") or a string[] (e.g. "agents"): a string
+ *     value matches by equality, an array value matches if any element is in
+ *     `fromAllowList`.
+ *   - `grantFields` defaulting to `[]` means a caller that declares NO grants
+ *     gets EXACTLY the 0.4.0 behaviour, byte-for-byte — this is a pure
+ *     widening, no existing caller's behaviour changes without an explicit
+ *     opt-in declaration at its own call site.
+ *   - This closes the OTHER pole of the fail-closed defect: 0.3.0/0.4.0
+ *     closed "a right granted by ABSENCE" (missing oauthCtx silently passing
+ *     everything); this closes "a right REFUSED by absence" — a grant that
+ *     IS present on the row (a named agent, pilot, or fulfiller) but that the
+ *     filter was structurally blind to because it only ever consulted
+ *     createdBy/namespace.
+ *
  * Contract (0.3.0 — BREAKING vs. 0.2.0):
  *   - `oauthCtx` is now MANDATORY. A right is never granted by absence: the
  *     0.2.0 behaviour of `oauthCtx === undefined` silently passing everything
@@ -50,6 +75,18 @@ export type ScopeFilterable = {
  * `fromAllowList` contains the `"*"` sentinel.
  */
 export declare function isMasterScope(ctx: OAuthCtx): boolean;
+/**
+ * Names of row properties the CALLER declares as per-row grants. Each named
+ * property's runtime value must be a `string` (single identity) or
+ * `string[]` (multiple identities) to be consulted — any other runtime shape
+ * is silently skipped (not a match), never thrown, since these are duck-typed
+ * against arbitrary Convex documents.
+ *
+ * This is DATA supplied by the call site, never a list hardcoded inside this
+ * package: the package does not and must not know that "agents" means
+ * missions or "fulfilledBy" means mandates.
+ */
+export type GrantFieldDeclaration = readonly string[];
 /**
  * Core predicate. Returns true when the row is visible to the caller.
  *
@@ -57,6 +94,9 @@ export declare function isMasterScope(ctx: OAuthCtx): boolean;
  *   - row.createdBy ∈ oauthCtx.fromAllowList           → true
  *   - row.namespace === prefix OR startsWith prefix+'/'
  *     for any prefix ∈ oauthCtx.namespaceReadPrefixes  → true
+ *   - row[grantField] (for any declared grantField) names an identity in
+ *     oauthCtx.fromAllowList, where the field is a string (equality) or a
+ *     string[] (any-element membership)                → true
  *   - otherwise                                        → false
  *
  * `oauthCtx` is mandatory (see module-level contract note above): an omitted
@@ -64,21 +104,32 @@ export declare function isMasterScope(ctx: OAuthCtx): boolean;
  * need the old legacy-bearer wildcard behaviour must pass `LEGACY_WILDCARD_CTX`
  * explicitly.
  *
+ * `grantFields` (0.5.0, optional, defaults to `[]`) lets a caller widen the
+ * predicate for its own table without this package hardcoding which fields
+ * are grants — see the module-level 0.5.0 contract note above. Omitting it
+ * (or passing `[]`) reproduces 0.4.0 behaviour exactly.
+ *
  * Substring matches that don't fall on a '/' boundary are explicitly rejected
  * (e.g. namespace="orchestrator/alphabet" does NOT match prefix
  * "orchestrator/alpha"). This avoids the classic prefix-isolation bypass.
  */
-export declare function passesScopeFilter(oauthCtx: OAuthCtx, row: ScopeFilterable): boolean;
+export declare function passesScopeFilter<T extends ScopeFilterable>(oauthCtx: OAuthCtx, row: T, grantFields?: GrantFieldDeclaration): boolean;
 /**
  * Filter a list of rows (post-query). Used by list_* tools.
+ *
+ * `grantFields` — see `passesScopeFilter`. Defaults to `[]` (0.4.0-identical
+ * behaviour).
  */
-export declare function scopeFilterList<T extends ScopeFilterable>(oauthCtx: OAuthCtx, rows: T[]): T[];
+export declare function scopeFilterList<T extends ScopeFilterable>(oauthCtx: OAuthCtx, rows: T[], grantFields?: GrantFieldDeclaration): T[];
 /**
  * Assert a single row passes (get_* tools). Returns the row when allowed, null
  * otherwise — callers translate null to a 404-equivalent "not found" MCP error
  * to avoid leaking the difference between "absent" and "filtered out".
+ *
+ * `grantFields` — see `passesScopeFilter`. Defaults to `[]` (0.4.0-identical
+ * behaviour).
  */
-export declare function scopeFilterGet<T extends ScopeFilterable>(oauthCtx: OAuthCtx, row: T | null | undefined): T | null;
+export declare function scopeFilterGet<T extends ScopeFilterable>(oauthCtx: OAuthCtx, row: T | null | undefined, grantFields?: GrantFieldDeclaration): T | null;
 /**
  * Helper for callers that want a single "is master / legacy" predicate.
  */

package/dist/scope-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-filter.d.ts","sourceRoot":"","sources":["../src/scope-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAKjC,CAAC;AAWF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAIpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,eAAe,GACnB,OAAO,CAYT;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,CAAC,EAAE,GACR,CAAC,EAAE,CAGL;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EACtD,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACxB,CAAC,GAAG,IAAI,CAIV;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAGtD"}
+{"version":3,"file":"scope-filter.d.ts","sourceRoot":"","sources":["../src/scope-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAKjC,CAAC;AAWF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAIpD;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,MAAM,EAAE,CAAC;AActD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,eAAe,EACzD,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,CAAC,EACN,WAAW,GAAE,qBAAuC,GACnD,OAAO,CAgBT;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,CAAC,EAAE,EACT,WAAW,GAAE,qBAAuC,GACnD,CAAC,EAAE,CAGL;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EACtD,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EACzB,WAAW,GAAE,qBAAuC,GACnD,CAAC,GAAG,IAAI,CAIV;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAGtD"}

package/dist/scope-filter.js

@@ -5,6 +5,31 @@
  * implementation; the only change was replacing a framework-specific context
  * type with the framework-agnostic `OAuthCtx` from `./types`.
  *
+ * Contract (0.5.0 — additive, widening only, vs. 0.4.0):
+ *   - Every exported predicate/filter now accepts an OPTIONAL `grantFields`
+ *     parameter: `readonly string[]`, defaulting to `[]`. Each entry names a
+ *     property on the row that the CALLER declares as a per-row grant (e.g.
+ *     "agents", "pilot", "fulfilledBy"). The package never hardcodes which
+ *     fields are grants for which table — that declaration is data supplied
+ *     by the caller at the call site, not business knowledge baked into this
+ *     shared module (no-hardcoded-business-knowledge).
+ *   - A row passes for a non-master caller if createdBy/namespace already
+ *     passed (0.4.0 behaviour, unchanged) OR if ANY declared grant field's
+ *     value names an identity in `oauthCtx.fromAllowList` — the field may be
+ *     a single string (e.g. "pilot") or a string[] (e.g. "agents"): a string
+ *     value matches by equality, an array value matches if any element is in
+ *     `fromAllowList`.
+ *   - `grantFields` defaulting to `[]` means a caller that declares NO grants
+ *     gets EXACTLY the 0.4.0 behaviour, byte-for-byte — this is a pure
+ *     widening, no existing caller's behaviour changes without an explicit
+ *     opt-in declaration at its own call site.
+ *   - This closes the OTHER pole of the fail-closed defect: 0.3.0/0.4.0
+ *     closed "a right granted by ABSENCE" (missing oauthCtx silently passing
+ *     everything); this closes "a right REFUSED by absence" — a grant that
+ *     IS present on the row (a named agent, pilot, or fulfiller) but that the
+ *     filter was structurally blind to because it only ever consulted
+ *     createdBy/namespace.
+ *
  * Contract (0.3.0 — BREAKING vs. 0.2.0):
  *   - `oauthCtx` is now MANDATORY. A right is never granted by absence: the
  *     0.2.0 behaviour of `oauthCtx === undefined` silently passing everything
@@ -57,6 +82,15 @@ export function isMasterScope(ctx) {
         return true;
     return ctx.fromAllowList.includes("*");
 }
+const NO_GRANT_FIELDS = [];
+function grantFieldMatches(value, fromAllowList) {
+    if (typeof value === "string")
+        return fromAllowList.includes(value);
+    if (Array.isArray(value)) {
+        return value.some((entry) => typeof entry === "string" && fromAllowList.includes(entry));
+    }
+    return false;
+}
 /**
  * Core predicate. Returns true when the row is visible to the caller.
  *
@@ -64,6 +98,9 @@ export function isMasterScope(ctx) {
  *   - row.createdBy ∈ oauthCtx.fromAllowList           → true
  *   - row.namespace === prefix OR startsWith prefix+'/'
  *     for any prefix ∈ oauthCtx.namespaceReadPrefixes  → true
+ *   - row[grantField] (for any declared grantField) names an identity in
+ *     oauthCtx.fromAllowList, where the field is a string (equality) or a
+ *     string[] (any-element membership)                → true
  *   - otherwise                                        → false
  *
  * `oauthCtx` is mandatory (see module-level contract note above): an omitted
@@ -71,11 +108,16 @@ export function isMasterScope(ctx) {
  * need the old legacy-bearer wildcard behaviour must pass `LEGACY_WILDCARD_CTX`
  * explicitly.
  *
+ * `grantFields` (0.5.0, optional, defaults to `[]`) lets a caller widen the
+ * predicate for its own table without this package hardcoding which fields
+ * are grants — see the module-level 0.5.0 contract note above. Omitting it
+ * (or passing `[]`) reproduces 0.4.0 behaviour exactly.
+ *
  * Substring matches that don't fall on a '/' boundary are explicitly rejected
  * (e.g. namespace="orchestrator/alphabet" does NOT match prefix
  * "orchestrator/alpha"). This avoids the classic prefix-isolation bypass.
  */
-export function passesScopeFilter(oauthCtx, row) {
+export function passesScopeFilter(oauthCtx, row, grantFields = NO_GRANT_FIELDS) {
     assertOauthCtx(oauthCtx);
     if (isMasterScope(oauthCtx))
         return true;
@@ -90,25 +132,36 @@ export function passesScopeFilter(oauthCtx, row) {
                 return true;
         }
     }
+    for (const field of grantFields) {
+        const value = row[field];
+        if (grantFieldMatches(value, oauthCtx.fromAllowList))
+            return true;
+    }
     return false;
 }
 /**
  * Filter a list of rows (post-query). Used by list_* tools.
+ *
+ * `grantFields` — see `passesScopeFilter`. Defaults to `[]` (0.4.0-identical
+ * behaviour).
  */
-export function scopeFilterList(oauthCtx, rows) {
+export function scopeFilterList(oauthCtx, rows, grantFields = NO_GRANT_FIELDS) {
     assertOauthCtx(oauthCtx);
-    return rows.filter((r) => passesScopeFilter(oauthCtx, r));
+    return rows.filter((r) => passesScopeFilter(oauthCtx, r, grantFields));
 }
 /**
  * Assert a single row passes (get_* tools). Returns the row when allowed, null
  * otherwise — callers translate null to a 404-equivalent "not found" MCP error
  * to avoid leaking the difference between "absent" and "filtered out".
+ *
+ * `grantFields` — see `passesScopeFilter`. Defaults to `[]` (0.4.0-identical
+ * behaviour).
  */
-export function scopeFilterGet(oauthCtx, row) {
+export function scopeFilterGet(oauthCtx, row, grantFields = NO_GRANT_FIELDS) {
     assertOauthCtx(oauthCtx);
     if (row == null)
         return null;
-    return passesScopeFilter(oauthCtx, row) ? row : null;
+    return passesScopeFilter(oauthCtx, row, grantFields) ? row : null;
 }
 /**
  * Helper for callers that want a single "is master / legacy" predicate.

package/dist/scope-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope-filter.js","sourceRoot":"","sources":["../src/scope-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAa;IAC3C,KAAK,EAAE,QAAQ;IACf,aAAa,EAAE,CAAC,GAAG,CAAC;IACpB,qBAAqB,EAAE,EAAE;IACzB,sBAAsB,EAAE,EAAE;CAC3B,CAAC;AAEF,SAAS,cAAc,CAAC,QAAkB;IACxC,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,SAAS,CACjB,2EAA2E;YACzE,0EAA0E,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAa;IACzC,cAAc,CAAC,GAAG,CAAC,CAAC;IACpB,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAkB,EAClB,GAAoB;IAEpB,cAAc,CAAC,QAAQ,CAAC,CAAC;IACzB,IAAI,aAAa,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC;IACrC,IAAI,SAAS,IAAI,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,qBAAqB,EAAE,CAAC;YAC/C,IAAI,SAAS,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACjC,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAkB,EAClB,IAAS;IAET,cAAc,CAAC,QAAQ,CAAC,CAAC;IACzB,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAkB,EAClB,GAAyB;IAEzB,cAAc,CAAC,QAAQ,CAAC,CAAC;IACzB,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAa;IAC3C,cAAc,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"scope-filter.js","sourceRoot":"","sources":["../src/scope-filter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/cloud-identity",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud (multi-tenant MCP).",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,6 +29,10 @@
     "./tenancy-domain": {
       "types": "./dist/tenancy-domain.d.ts",
       "import": "./dist/tenancy-domain.js"
+    },
+    "./human-path": {
+      "types": "./dist/human-path.d.ts",
+      "import": "./dist/human-path.js"
     }
   },
   "files": [