@vantageos/cloud-identity 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/cloud-identity",
-  "version": "0.3.0",
+  "version": "0.4.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": [