@vantageos/cloud-identity 0.2.0 → 0.4.0

package/README.md

@@ -1,8 +1,16 @@
 # @vantageos/cloud-identity
 
-Framework-agnostic identity + scope-filter primitives for **VantagePeers Cloud** (multi-tenant MCP).
+Building blocks for multi-tenant authorization: decide which tenant a caller
+belongs to, and keep every other tenant's rows out of the response.
 
-Consumed by `vantage-peers-mcp` and `@vantageos/vantage-crm-mcp` — provides the small, testable building blocks that gate cross-tenant data access in the MCP transport layer.
+If your service holds data for several customers behind one deployment, you
+answer the same four questions on every request — who is calling, which tenant
+they belong to, which rows they may see, and whether their token is genuine.
+This package answers them once, in plain functions with no framework attached,
+so each service does not re-implement (and re-misimplement) its own version.
+
+It depends on no web framework, router or database, and runs anywhere
+JavaScript runs.
 
 ## Install
 
@@ -10,182 +18,298 @@ Consumed by `vantage-peers-mcp` and `@vantageos/vantage-crm-mcp` — provides th
 npm install @vantageos/cloud-identity
 ```
 
-## Modules
-
-| Module | Symbols | Purpose |
-| --- | --- | --- |
-| `@vantageos/cloud-identity/crypto` | `timingSafeEqual` | Constant-time byte comparison (no branch-timing leak). |
-| `@vantageos/cloud-identity/scope-filter` | `passesScopeFilter`, `scopeFilterList`, `scopeFilterGet` | Row-level visibility filter on `(createdBy, namespace)` using the caller's OAuth scope. |
-| `@vantageos/cloud-identity/bearer-validation` | `validateMasterBearer` | Bearer-token parsing + sha256 constant-time match against a configured master secret. |
-| `@vantageos/cloud-identity/types` | `OAuthCtx`, `ScopeProfile`, `NamespacePrefix`, `FromAllowListEntry`, `ValidateMasterBearerResult` | Public type surface (0.1.0). |
-| `@vantageos/cloud-identity/tenancy-domain` | `Workspace`, `WorkspaceMember`, `WorkspaceRole`, `TenantContext`, `workspaceSchema`, `workspaceMemberSchema`, `workspaceRoleSchema`, `tenantContextSchema`, `ScopeViolationError`, `getEffectiveTenantId`, `decodeUnverifiedBearer` | Domain-tenancy layer (0.2.0) — multi-tenant isolation guard + Zod schemas + bearer DECODER (not auth — see security note). |
-
-## 0.1.0 scope
-
-This release ships the **transport-agnostic** core:
-
-- `crypto.timingSafeEqual`
-- `scope-filter.{passesScopeFilter, scopeFilterList, scopeFilterGet}`
-- `bearer-validation.validateMasterBearer`
-- types
+Node 18 or later. ESM only.
 
-## 0.2.0 domain-tenancy layer
+## Quick start
 
-Released 2026-06-13. Additive — no breaking changes.
+```js
+import { requireTenantId, scopeFilterList } from "@vantageos/cloud-identity";
 
-New in 0.2.0:
-- `WorkspaceRole` literal union + Zod schema
-- `Workspace` + `WorkspaceMember` + `TenantContext` types + Zod schemas
-- `ScopeViolationError` — canonical cross-tenant isolation error
-- `getEffectiveTenantId(ctx, args)` — multi-tenant guard (call at the top of every tool handler)
-- `decodeUnverifiedBearer(token)` — DECODE-ONLY helper. ⚠️ NOT authentication. NOT a trust boundary. See [Security: bearer decoding](#security-bearer-decoding) below.
+// 1. Which tenant is this caller in? Throws if the answer is "none".
+const tenantId = requireTenantId({
+  kind: "session",
+  identity: { userId: "user_123", orgId: "org_abc" },
+});
 
-## 0.3.0 roadmap
-
-- D1 ghost Clerk identity injection.
-- Signed-JWT bearer verification (replacing the decode-only helper as the production trust boundary).
-- Co-designed in a Theta cycle.
-
-## Usage examples
-
-### Constant-time byte comparison
-
-```ts
-import { timingSafeEqual } from "@vantageos/cloud-identity/crypto";
-
-const a = new TextEncoder().encode(presentedHash);
-const b = new TextEncoder().encode(expectedHash);
-if (!(await timingSafeEqual(a, b))) {
-  return new Response("forbidden", { status: 403 });
-}
-```
-
-### Scope-aware row filtering
-
-```ts
-import { scopeFilterList } from "@vantageos/cloud-identity/scope-filter";
-import type { OAuthCtx } from "@vantageos/cloud-identity/types";
-
-const ctx: OAuthCtx = {
-  fromAllowList: ["alice"],
-  namespaceReadPrefixes: ["orchestrator/alpha"],
+// 2. Which of these rows may they see?
+const ctx = {
+  fromAllowList: ["reports"],
+  namespaceReadPrefixes: ["team/finance"],
   namespaceWritePrefixes: [],
 };
-const visible = scopeFilterList(ctx, rowsFromConvex);
-```
 
-### Master Bearer validation
+const rows = [
+  { createdBy: "reports", namespace: "team/finance" },    // kept
+  { createdBy: "someone-else", namespace: "team/legal" }, // dropped
+];
 
-```ts
-import { validateMasterBearer } from "@vantageos/cloud-identity/bearer-validation";
-
-const res = await validateMasterBearer(
-  request.headers.get("authorization") ?? undefined,
-  process.env.BEARER_SECRET_MASTER ?? "",
-);
-if (!res.ok) {
-  return new Response(`unauthorized: ${res.error}`, { status: 401 });
-}
+console.log(tenantId);                    // "org_abc"
+console.log(scopeFilterList(ctx, rows));  // only the first row
 ```
 
-### Domain-tenancy layer (0.2.0)
-
-#### getEffectiveTenantId — multi-tenant isolation guard
+Every symbol is available from the package root. Subpath imports
+(`@vantageos/cloud-identity/scope-filter` and friends) also work if you prefer
+to be explicit about where something comes from.
 
-```ts
-import { getEffectiveTenantId, ScopeViolationError } from "@vantageos/cloud-identity/tenancy-domain";
-import type { TenantContext } from "@vantageos/cloud-identity/tenancy-domain";
-
-// 1. Obtain ctx from your VERIFIED auth middleware. Examples:
-//    - Clerk session (clerkClient.verifyToken + claims → TenantContext)
-//    - signed-JWT middleware (jose / jsonwebtoken with public key)
-//    - Convex tenancy-table lookup against an opaque token
-//    Whatever path: ctx.workspaceId MUST come from a SIGNATURE-VERIFIED source.
-const ctx: TenantContext = await verifiedAuthMiddleware(request);
-
-// 2. At the top of every tool handler that receives a workspaceId argument:
-try {
-  const tenantId = getEffectiveTenantId(ctx, args);
-  // tenantId is safe — caller's verified ctx matches the requested workspace
-  const rows = await db.list({ workspaceId: tenantId });
-} catch (err) {
-  if (err instanceof ScopeViolationError) {
-    // Translate to 403 — do NOT expose details to caller
-    return new Response("forbidden", { status: 403 });
-  }
-  throw err;
-}
-```
+## Both caller paths, one contract
 
-#### decodeUnverifiedBearer — DECODE-ONLY helper
-
-> ⚠️ **NOT AUTHENTICATION. NOT A TRUST BOUNDARY.** See the [Security: bearer decoding](#security-bearer-decoding) section below.
+A right is never granted by an absent argument. `requireTenantId` refuses by
+default — a missing session, a missing organization, or a missing
+bearer-resolved workspace all throw; there is no branch that falls through to
+"full access" when tenant information is absent. The same function resolves
+both entry paths a VantagePeers Cloud request can arrive on:
 
 ```ts
-import { decodeUnverifiedBearer } from "@vantageos/cloud-identity/tenancy-domain";
-
-// Use cases:
-//   (a) tests / fixtures
-//   (b) shape-inspection of a payload that was ALREADY verified upstream
-//
-// Do NOT feed the returned `workspaceId` into getEffectiveTenantId as the
-// trusted `ctx.workspaceId` — the payload is attacker-controlled.
-
-const token = Buffer.from(JSON.stringify({
-  userId: "user_alice",
-  workspaceId: "ws_prod",
-  roles: ["Admin"],
-})).toString("base64");
-
-const { userId, workspaceId, roles } = await decodeUnverifiedBearer(token);
-```
-
-#### Zod schemas — validate workspace objects at boundaries
+import {
+  requireTenantId,
+  decodeUnverifiedBearer,
+  type TenantSource,
+} from "@vantageos/cloud-identity";
+
+async function resolveTenant(req: {
+  session?: { orgId?: string | null } | null;
+  bearerToken?: string;
+}): Promise<string> {
+  const source: TenantSource = req.session
+    ? { kind: "session", identity: req.session }
+    : {
+        // decodeUnverifiedBearer only decodes the shape — verify the token's
+        // signature (or look it up against your own store) before trusting
+        // any field on the payload. See "What this package does not do".
+        kind: "bearer",
+        context: await decodeUnverifiedBearer(req.bearerToken!),
+      };
+
+  // Throws for BOTH paths if no tenant is attached — never returns a
+  // "default" tenant id when one is missing.
+  return requireTenantId(source);
+}
 
-```ts
-import { workspaceSchema, tenantContextSchema } from "@vantageos/cloud-identity/tenancy-domain";
+// Human path: a signed-in user with an active organization.
+await resolveTenant({ session: { orgId: "org_abc" } }); // -> "org_abc"
 
-// Validate at API boundary
-const ws = workspaceSchema.parse(requestBody);
+// Machine path: a caller presenting an already-resolved bearer token.
+await resolveTenant({ bearerToken: someBase64Token }); // -> the token's workspaceId
 
-// Validate TenantContext from an external JWT payload
-const ctx = tenantContextSchema.parse(jwtPayload);
+// Either path with nothing attached throws instead of granting access.
+await resolveTenant({ session: null }); // throws Error("Unauthenticated: no session.")
 ```
 
-## Security: bearer decoding
-
-`decodeUnverifiedBearer` performs **no signature verification, no issuer check, no expiry check, no replay-attack protection**. The decoded payload is **attacker-controlled**.
-
-Forgery example:
-
-```ts
-// Any attacker can produce this token — no key, no signature required.
-const forged = Buffer.from(JSON.stringify({
-  userId: "x",
-  workspaceId: "victim-org",     // crosses tenant boundary
-  roles: ["Admin"],              // elevates privileges
-})).toString("base64");
-
-const payload = await decodeUnverifiedBearer(forged); // accepts it
+## What each function does
+
+**Tenant resolution and membership**
+
+- `requireTenantId(source)` — returns the caller's tenant id, or throws if
+  there is none. It accepts both entry paths behind one contract:
+  `{ kind: "session", identity }` for a signed-in human, and
+  `{ kind: "bearer", context }` for a machine caller. A missing session, a
+  missing organization and an empty organization id are all refusals, never a
+  default.
+- `getEffectiveTenantId(ctx, args)` — resolves which tenant a request should
+  act on when a caller may legitimately act on more than one.
+
+**Row filtering**
+
+- `passesScopeFilter(ctx, row)` — true when this row is visible to this
+  caller.
+- `scopeFilterList(ctx, rows)` — the subset of rows the caller may see.
+- `scopeFilterGet(ctx, row)` — the row, or `null` if the caller may not see it.
+- `isMasterScope(ctx)` / `isWildcardScope(ctx)` — true when the caller holds
+  unrestricted access. Useful for skipping filtering you know is pointless;
+  never as a substitute for it.
+
+Visibility is granted two ways: the row's `createdBy` appears in the caller's
+`fromAllowList`, or the row's `namespace` sits under one of the caller's
+`namespaceReadPrefixes`. Prefixes match on a path boundary, so a caller allowed
+`team/finance` does not thereby see `team/finance-archive`.
+
+**Token validation**
+
+- `validateMasterBearer(header, secret)` — compares an `Authorization: Bearer`
+  header against a shared secret in constant time, and reports *why* it failed:
+  header absent, header malformed, or value mismatched.
+- `timingSafeEqual(a, b)` — constant-time byte comparison, if you need to build
+  your own check.
+
+**Shapes**
+
+Zod schemas and their inferred TypeScript types for workspaces, members,
+roles and tenant context: `workspaceSchema` (type `Workspace`),
+`workspaceMemberSchema` (type `WorkspaceMember`), `workspaceRoleSchema`
+(type `WorkspaceRole`), `tenantContextSchema` (type `TenantContext`) — plus
+`ScopeViolationError` (payload type `ScopeViolationPayload`), for refusals you
+want to catch by type, and `BearerPayload`, the type returned by
+`decodeUnverifiedBearer`.
+
+**Supporting types** (no runtime code — import with `import type`)
+
+- `OAuthCtx` — the context object every scope-filter function above requires:
+  `{ fromAllowList, namespaceReadPrefixes, namespaceWritePrefixes, scope? }`.
+- `ScopeProfile`, `NamespacePrefix`, `FromAllowListEntry` — the field types
+  that make up `OAuthCtx`.
+- `ValidateMasterBearerResult` — the return type of `validateMasterBearer`.
+- `ScopeFilterable` — the minimal row shape (`{ createdBy?, namespace? }`)
+  accepted by `passesScopeFilter` / `scopeFilterList` / `scopeFilterGet`.
+- `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 }`, `{ 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
+
+Worth reading before you rely on it.
+
+- **`decodeUnverifiedBearer` decodes a token. It does not verify one.** The
+  name is literal. It reads the payload out of a bearer token and checks its
+  shape; it does not check a signature, so the contents are whatever the caller
+  chose to put there. Treating its output as trusted is a vulnerability, not a
+  shortcut. Verify the token — a signed JWT, or a lookup against your own store
+  — before you believe any field in it.
+- **This is not an authentication system.** There is no user store, no login,
+  no session issuance. It takes an identity you have already established and
+  tells you what that identity may reach.
+- **It does not talk to your database.** `scopeFilterList` filters rows you
+  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.**
+
+Before 0.3.0, calling a scope-filter function without an authorization context
+returned `true` — no context meant full access. A caller who simply forgot to
+pass the context received every row, and no warning. From 0.3.0 the context is
+required: omitting it is a type error, and passing `null` or `undefined`
+throws.
+
+The breakage is deliberate, and it is the point. A caller that stops compiling
+is a caller that has been told. A caller that still compiles and quietly
+returns different rows is an incident nobody attributes to the upgrade.
+
+What to do:
+
+- If the call site has a real authorization context, pass it. This is almost
+  always the right fix, and the context is usually already in scope.
+- If the call site genuinely means "unrestricted", pass the exported constant
+  `LEGACY_WILDCARD_CTX` by name. It reproduces the old behaviour exactly. It
+  has to be written out, because an intentional bypass belongs in a code review
+  and an accidental one should not be possible.
+
+```js
+import { scopeFilterList, LEGACY_WILDCARD_CTX } from "@vantageos/cloud-identity";
+
+scopeFilterList(LEGACY_WILDCARD_CTX, rows); // explicit, unrestricted
 ```
 
-Feeding the decoded `workspaceId` into `getEffectiveTenantId` as the trusted `ctx.workspaceId` silently grants cross-tenant access — the multi-tenant isolation guard collapses because both `ctx` and `args` are then attacker-controlled.
+`requireTenantId` is also new in 0.3.0. Nothing existing calls it, so it breaks
+nothing.
 
-**Use only as**:
-- a test fixture / harness helper, OR
-- a decoder for a bearer that was ALREADY verified by an upstream signed-JWT or opaque-token middleware (the production trust boundary).
+Version history is in [CHANGELOG.md](./CHANGELOG.md).
 
-**Production trust boundary** is one of:
-- Clerk session verification (planned 0.3.0 D1 ghost identity injection)
-- signed JWT with rotating issuer key (planned 0.3.0)
-- opaque-token lookup against a Convex tenancy table
-
-Do **not** publish a service that treats `decodeUnverifiedBearer` as authentication.
-
-## Security doctrine
+## License
 
-Canonical reference: `docs/cloud/security-multi-tenant.md` in the `vantage-peers` repo.
+FSL-1.1-Apache-2.0. See [LICENSE](./LICENSE).
 
-## License
+## Issues
 
-MIT — VantagePeers Cloud, 2026.
+https://github.com/vantageos-agency/cloud-identity/issues

package/dist/bearer-validation.d.ts

@@ -1,9 +1,8 @@
 /**
  * Master-token Bearer validation.
  *
- * Extracted from the master-gate logic in
- * `vantage-memory/mcp-server/server-http.ts` (`masterOnlyMiddleware`) and
- * HARDENED per @vantageos/cloud-identity 0.1.0 contract:
+ * Extracted from an earlier in-tree master-gate middleware and HARDENED per
+ * this package's contract:
  *   - SHA-256 hash both the presented token AND the configured master secret,
  *     then compare the two digests with `timingSafeEqual` (constant time).
  *   - The original middleware did a direct `token !== masterToken` string

package/dist/bearer-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bearer-validation.d.ts","sourceRoot":"","sources":["../src/bearer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAU7D;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,0BAA0B,CAAC,CAsBrC"}
+{"version":3,"file":"bearer-validation.d.ts","sourceRoot":"","sources":["../src/bearer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAU7D;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,0BAA0B,CAAC,CAsBrC"}

package/dist/bearer-validation.js

@@ -1,9 +1,8 @@
 /**
  * Master-token Bearer validation.
  *
- * Extracted from the master-gate logic in
- * `vantage-memory/mcp-server/server-http.ts` (`masterOnlyMiddleware`) and
- * HARDENED per @vantageos/cloud-identity 0.1.0 contract:
+ * Extracted from an earlier in-tree master-gate middleware and HARDENED per
+ * this package's contract:
  *   - SHA-256 hash both the presented token AND the configured master secret,
  *     then compare the two digests with `timingSafeEqual` (constant time).
  *   - The original middleware did a direct `token !== masterToken` string

package/dist/bearer-validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"bearer-validation.js","sourceRoot":"","sources":["../src/bearer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAEtC,KAAK,UAAU,WAAW,CAAC,KAAa;IACtC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3D,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAA8B,EAC9B,YAAoB;IAEpB,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACzE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC3C,CAAC;IACD,sEAAsE;IACtE,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACpD,WAAW,CAAC,KAAK,CAAC;QAClB,WAAW,CAAC,YAAY,CAAC;KAC1B,CAAC,CAAC;IACH,MAAM,EAAE,GAAG,MAAM,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAC5D,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"bearer-validation.js","sourceRoot":"","sources":["../src/bearer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAEtC,KAAK,UAAU,WAAW,CAAC,KAAa;IACtC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3D,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAA8B,EAC9B,YAAoB;IAEpB,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACzE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC3C,CAAC;IACD,sEAAsE;IACtE,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACpD,WAAW,CAAC,KAAK,CAAC;QAClB,WAAW,CAAC,YAAY,CAAC;KAC1B,CAAC,CAAC;IACH,MAAM,EAAE,GAAG,MAAM,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAC5D,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC9D,CAAC"}

package/dist/crypto.d.ts

@@ -1,11 +1,9 @@
 /**
  * Constant-time byte-array comparison.
  *
- * Ported from `vantage-memory/mcp-server/src/crypto.ts` (Day 47 master-token
- * gate, Eta F1 MAJOR PR #621). Surface adapted from `(string, string)` to
- * `(Uint8Array, Uint8Array)` per @vantageos/cloud-identity 0.1.0 contract so
- * the helper is framework-agnostic and reusable by any caller (hash bytes,
- * raw token bytes, HMAC tags, etc.).
+ * Takes `(Uint8Array, Uint8Array)` rather than strings so the helper stays
+ * framework-agnostic and reusable by any caller: hash bytes, raw token
+ * bytes, HMAC tags.
  *
  * Algorithm (identical to source):
  *   1. Length mismatch → still run a dummy Web Crypto HMAC over equal-length

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CACnC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB"}

package/dist/crypto.js

@@ -1,11 +1,9 @@
 /**
  * Constant-time byte-array comparison.
  *
- * Ported from `vantage-memory/mcp-server/src/crypto.ts` (Day 47 master-token
- * gate, Eta F1 MAJOR PR #621). Surface adapted from `(string, string)` to
- * `(Uint8Array, Uint8Array)` per @vantageos/cloud-identity 0.1.0 contract so
- * the helper is framework-agnostic and reusable by any caller (hash bytes,
- * raw token bytes, HMAC tags, etc.).
+ * Takes `(Uint8Array, Uint8Array)` rather than strings so the helper stays
+ * framework-agnostic and reusable by any caller: hash bytes, raw token
+ * bytes, HMAC tags.
  *
  * Algorithm (identical to source):
  *   1. Length mismatch → still run a dummy Web Crypto HMAC over equal-length

package/dist/crypto.js.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,CAAa,EACb,CAAa;IAEb,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACxC,KAAK,EACL,WAAsC,EACtC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAC;QACF,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,KAAgC,CAAC,CAAC;QACzE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC"}
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,CAAa,EACb,CAAa;IAEb,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACxC,KAAK,EACL,WAAsC,EACtC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAC;QACF,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,KAAgC,CAAC,CAAC;QACzE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC"}

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