@vantageos/cloud-identity 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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.2.0] - 2026-06-13
+
+Additive release — domain-tenancy layer. No breaking changes. All 0.1.0 exports unchanged.
+
+### Added
+
+- `WorkspaceRole` literal union `"Admin" | "Editor" | "Viewer"` + `workspaceRoleSchema` (Zod).
+- `Workspace` type + `workspaceSchema` (Zod) — `{ id, name, createdAt, metadata? }`.
+- `WorkspaceMember` type + `workspaceMemberSchema` (Zod) — `{ userId, workspaceId, role, joinedAt }`.
+- `TenantContext` type + `tenantContextSchema` (Zod) — `{ workspaceId, userId, roles[] }`.
+- `ScopeViolationError` class — `code: "SCOPE_VIOLATION"`, payload `{ requestedTenantId, contextTenantId, reason }`. Canonical cross-tenant isolation signal — translate to 403 or MCP permission-denied.
+- `getEffectiveTenantId(ctx, args)` — multi-tenant isolation guard. Throws `ScopeViolationError` when `args.workspaceId !== ctx.workspaceId`; returns `ctx.workspaceId` on match.
+- `decodeUnverifiedBearer(token)` — async DECODER for `base64(JSON({ userId, workspaceId, roles[] }))` into `BearerPayload`. Validates SHAPE via Zod and throws on shape or decode failure. **⚠️ NOT authentication. NOT a trust boundary.** Performs NO signature verification, NO issuer check, NO expiry check. The decoded payload is attacker-controlled — see the "Security: bearer decoding" section of README. Use as a test fixture or as a decoder for a bearer already verified by an upstream signed-JWT / opaque-token middleware. The production trust boundary (signed JWT + verification) is planned for 0.3.0. Renamed from the original `resolveBearer` (0.2.0 pre-release) per Eta security review — the new name makes the lack of verification impossible to miss at the call-site.
+- `BearerPayload` type (inferred from Zod schema).
+- `ScopeViolationPayload` interface.
+- New subpath export: `@vantageos/cloud-identity/tenancy-domain`.
+- `zod` added as a production dependency (schema validation for domain types).
+
+### Notes
+
+- All new symbols are also re-exported from the main `@vantageos/cloud-identity` entry point.
+- `decodeUnverifiedBearer` uses base64-JSON as a lightweight format and is intentionally NOT an authentication primitive. Production callers MUST run a SIGNATURE-VERIFYING middleware (signed JWT / Clerk session / opaque-token lookup) before constructing the `TenantContext` passed to `getEffectiveTenantId`.
+- `getEffectiveTenantId` expects a `TenantContext` whose `workspaceId` came from a signature-verified source. Feeding it the output of `decodeUnverifiedBearer` directly is a security bug — see README "Security: bearer decoding".
+
 ## [0.1.0] - 2026-06-04
 
 Initial release.

package/README.md

@@ -17,7 +17,8 @@ npm install @vantageos/cloud-identity
 | `@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. |
+| `@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
 
@@ -28,10 +29,21 @@ This release ships the **transport-agnostic** core:
 - `bearer-validation.validateMasterBearer`
 - types
 
-## 0.2.0 roadmap
+## 0.2.0 domain-tenancy layer
+
+Released 2026-06-13. Additive — no breaking changes.
+
+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.
+
+## 0.3.0 roadmap
 
-- `getEffectiveWorkspaceId` (workspace resolution helper, sourced from `vantageos-crm`).
 - 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
@@ -76,6 +88,100 @@ if (!res.ok) {
 }
 ```
 
+### Domain-tenancy layer (0.2.0)
+
+#### getEffectiveTenantId — multi-tenant isolation guard
+
+```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;
+}
+```
+
+#### decodeUnverifiedBearer — DECODE-ONLY helper
+
+> ⚠️ **NOT AUTHENTICATION. NOT A TRUST BOUNDARY.** See the [Security: bearer decoding](#security-bearer-decoding) section below.
+
+```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
+
+```ts
+import { workspaceSchema, tenantContextSchema } from "@vantageos/cloud-identity/tenancy-domain";
+
+// Validate at API boundary
+const ws = workspaceSchema.parse(requestBody);
+
+// Validate TenantContext from an external JWT payload
+const ctx = tenantContextSchema.parse(jwtPayload);
+```
+
+## 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
+```
+
+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.
+
+**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).
+
+**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
 
 Canonical reference: `docs/cloud/security-multi-tenant.md` in the `vantage-peers` repo.

package/dist/index.d.ts

@@ -9,4 +9,6 @@ export { timingSafeEqual } from "./crypto.js";
 export { passesScopeFilter, scopeFilterList, scopeFilterGet, isMasterScope, isWildcardScope, type ScopeFilterable, } from "./scope-filter.js";
 export { validateMasterBearer } from "./bearer-validation.js";
 export type { OAuthCtx, ScopeProfile, NamespacePrefix, FromAllowListEntry, ValidateMasterBearerResult, } from "./types.js";
+export { workspaceSchema, workspaceMemberSchema, workspaceRoleSchema, tenantContextSchema, ScopeViolationError, getEffectiveTenantId, decodeUnverifiedBearer, } from "./tenancy-domain.js";
+export type { Workspace, WorkspaceMember, WorkspaceRole, TenantContext, ScopeViolationPayload, BearerPayload, } from "./tenancy-domain.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,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"}
+{"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,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"}

package/dist/index.js

@@ -8,4 +8,6 @@
 export { timingSafeEqual } from "./crypto.js";
 export { passesScopeFilter, scopeFilterList, scopeFilterGet, isMasterScope, isWildcardScope, } from "./scope-filter.js";
 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";
 //# 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,GAEhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,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,GAEhB,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"}

package/dist/tenancy-domain.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @vantageos/cloud-identity 0.2.0 — Domain-tenancy layer.
+ *
+ * Additive-only: does not modify any 0.1.0 exports.
+ *
+ * Provides:
+ *   - WorkspaceRole literal union + Zod schema
+ *   - Workspace type + Zod schema
+ *   - WorkspaceMember type + Zod schema
+ *   - TenantContext type + Zod schema
+ *   - ScopeViolationError class (code: "SCOPE_VIOLATION")
+ *   - getEffectiveTenantId(ctx, args) — multi-tenant isolation guard
+ *   - decodeUnverifiedBearer(token) — DECODE-ONLY helper, NOT authentication.
+ *     The decoded payload is attacker-controlled. Production code MUST use a
+ *     signed JWT or opaque-token lookup (planned: 0.3.0) before treating the
+ *     payload as a trust boundary.
+ *
+ * Task: k177hejb4tc5em5p70m9hxwn3x88kyp4
+ * Mission: k57b4t2q VR Cloud MVP Day 100
+ * Orchestrator: Sigma — VantagePeers | 2026-06-13
+ */
+import { z } from "zod";
+export declare const workspaceRoleSchema: z.ZodEnum<{
+    Admin: "Admin";
+    Editor: "Editor";
+    Viewer: "Viewer";
+}>;
+export type WorkspaceRole = z.infer<typeof workspaceRoleSchema>;
+export declare const workspaceSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    createdAt: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type Workspace = z.infer<typeof workspaceSchema>;
+export declare const workspaceMemberSchema: z.ZodObject<{
+    userId: z.ZodString;
+    workspaceId: z.ZodString;
+    role: z.ZodEnum<{
+        Admin: "Admin";
+        Editor: "Editor";
+        Viewer: "Viewer";
+    }>;
+    joinedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type WorkspaceMember = z.infer<typeof workspaceMemberSchema>;
+export declare const tenantContextSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    userId: z.ZodString;
+    roles: z.ZodArray<z.ZodEnum<{
+        Admin: "Admin";
+        Editor: "Editor";
+        Viewer: "Viewer";
+    }>>;
+}, z.core.$strip>;
+export type TenantContext = z.infer<typeof tenantContextSchema>;
+export interface ScopeViolationPayload {
+    requestedTenantId: string;
+    contextTenantId: string;
+    reason: string;
+}
+/**
+ * Thrown by `getEffectiveTenantId` when `args.workspaceId` does not match the
+ * workspaceId encoded in the bearer-resolved `TenantContext`. This error is the
+ * canonical cross-tenant isolation signal across the VantagePeers Cloud fleet.
+ *
+ * Callers MUST translate this to a 403 or MCP permission-denied — never 404.
+ */
+export declare class ScopeViolationError extends Error {
+    readonly code: "SCOPE_VIOLATION";
+    readonly payload: ScopeViolationPayload;
+    constructor(payload: ScopeViolationPayload);
+}
+/**
+ * Resolve the effective tenant workspace ID from a `TenantContext` + request args.
+ *
+ * If `args.workspaceId` differs from the context's `workspaceId` (derived from
+ * the bearer token), a `ScopeViolationError` is thrown immediately.
+ *
+ * This is the primary multi-tenant isolation gate — call it at the top of every
+ * MCP tool handler that accepts a `workspaceId` argument.
+ *
+ * @example
+ * ```ts
+ * const tenantId = getEffectiveTenantId(ctx, args);
+ * // safe to use tenantId for DB queries — caller's scope is verified
+ * ```
+ */
+export declare function getEffectiveTenantId(ctx: TenantContext, args: {
+    workspaceId: string;
+}): string;
+/**
+ * @security ⚠️ DECODE-ONLY. NOT AUTHENTICATION. NOT A TRUST BOUNDARY.
+ *
+ * Decodes a `base64(JSON({ userId, workspaceId, roles[] }))` payload and
+ * validates its SHAPE with Zod. It performs NO signature verification, NO
+ * issuer check, NO expiry check, NO replay-attack protection. The decoded
+ * payload is attacker-controlled and MUST NOT be used as the source of
+ * truth for multi-tenant isolation.
+ *
+ * Forgery example: any attacker producing
+ *   base64(JSON({ userId:"x", workspaceId:"victim-org", roles:["Admin"] }))
+ * passes this function. Treating the returned `workspaceId` as authoritative
+ * — for example feeding it into `getEffectiveTenantId` as the trusted
+ * `ctx.workspaceId` — silently grants cross-tenant access.
+ *
+ * Use only as:
+ *   - test fixture / harness helper
+ *   - decoder for a bearer that was ALREADY verified by an upstream signed-JWT
+ *     middleware (the production trust boundary)
+ *
+ * For the production trust boundary, callers MUST substitute a signed JWT
+ * (planned export in 0.3.0) or an opaque-token lookup against a Convex
+ * tenancy table.
+ *
+ * Renamed from `resolveBearer` (0.2.0 pre-release) to make the lack of
+ * verification impossible to miss at the call-site.
+ */
+declare const bearerPayloadSchema: z.ZodObject<{
+    userId: z.ZodString;
+    workspaceId: z.ZodString;
+    roles: z.ZodArray<z.ZodEnum<{
+        Admin: "Admin";
+        Editor: "Editor";
+        Viewer: "Viewer";
+    }>>;
+}, z.core.$strip>;
+export type BearerPayload = z.infer<typeof bearerPayloadSchema>;
+export declare function decodeUnverifiedBearer(token: string): Promise<BearerPayload>;
+export {};
+//# sourceMappingURL=tenancy-domain.d.ts.map

package/dist/tenancy-domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenancy-domain.d.ts","sourceRoot":"","sources":["../src/tenancy-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,mBAAmB;;;;EAAwC,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,eAAe;;;;;iBAK1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAMxD,eAAO,MAAM,qBAAqB;;;;;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE,eAAO,MAAM,mBAAmB;;;;;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;IAC3C,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;gBAE5B,OAAO,EAAE,qBAAqB;CAS3C;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5B,MAAM,CASR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,QAAA,MAAM,mBAAmB;;;;;;;;iBAIvB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC,CAmBxB"}

package/dist/tenancy-domain.js

@@ -0,0 +1,152 @@
+/**
+ * @vantageos/cloud-identity 0.2.0 — Domain-tenancy layer.
+ *
+ * Additive-only: does not modify any 0.1.0 exports.
+ *
+ * Provides:
+ *   - WorkspaceRole literal union + Zod schema
+ *   - Workspace type + Zod schema
+ *   - WorkspaceMember type + Zod schema
+ *   - TenantContext type + Zod schema
+ *   - ScopeViolationError class (code: "SCOPE_VIOLATION")
+ *   - getEffectiveTenantId(ctx, args) — multi-tenant isolation guard
+ *   - decodeUnverifiedBearer(token) — DECODE-ONLY helper, NOT authentication.
+ *     The decoded payload is attacker-controlled. Production code MUST use a
+ *     signed JWT or opaque-token lookup (planned: 0.3.0) before treating the
+ *     payload as a trust boundary.
+ *
+ * Task: k177hejb4tc5em5p70m9hxwn3x88kyp4
+ * Mission: k57b4t2q VR Cloud MVP Day 100
+ * Orchestrator: Sigma — VantagePeers | 2026-06-13
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// WorkspaceRole
+// ---------------------------------------------------------------------------
+export const workspaceRoleSchema = z.enum(["Admin", "Editor", "Viewer"]);
+// ---------------------------------------------------------------------------
+// Workspace
+// ---------------------------------------------------------------------------
+export const workspaceSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    createdAt: z.number(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+// ---------------------------------------------------------------------------
+// WorkspaceMember
+// ---------------------------------------------------------------------------
+export const workspaceMemberSchema = z.object({
+    userId: z.string().min(1),
+    workspaceId: z.string().min(1),
+    role: workspaceRoleSchema,
+    joinedAt: z.number(),
+});
+// ---------------------------------------------------------------------------
+// TenantContext
+// ---------------------------------------------------------------------------
+export const tenantContextSchema = z.object({
+    workspaceId: z.string().min(1),
+    userId: z.string().min(1),
+    roles: z.array(workspaceRoleSchema),
+});
+/**
+ * Thrown by `getEffectiveTenantId` when `args.workspaceId` does not match the
+ * workspaceId encoded in the bearer-resolved `TenantContext`. This error is the
+ * canonical cross-tenant isolation signal across the VantagePeers Cloud fleet.
+ *
+ * Callers MUST translate this to a 403 or MCP permission-denied — never 404.
+ */
+export class ScopeViolationError extends Error {
+    code = "SCOPE_VIOLATION";
+    payload;
+    constructor(payload) {
+        super(`SCOPE_VIOLATION: requested tenant "${payload.requestedTenantId}" does not match context tenant "${payload.contextTenantId}" — ${payload.reason}`);
+        this.name = "ScopeViolationError";
+        this.payload = payload;
+        // Restore prototype chain (required for instanceof checks in transpiled targets).
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// getEffectiveTenantId
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the effective tenant workspace ID from a `TenantContext` + request args.
+ *
+ * If `args.workspaceId` differs from the context's `workspaceId` (derived from
+ * the bearer token), a `ScopeViolationError` is thrown immediately.
+ *
+ * This is the primary multi-tenant isolation gate — call it at the top of every
+ * MCP tool handler that accepts a `workspaceId` argument.
+ *
+ * @example
+ * ```ts
+ * const tenantId = getEffectiveTenantId(ctx, args);
+ * // safe to use tenantId for DB queries — caller's scope is verified
+ * ```
+ */
+export function getEffectiveTenantId(ctx, args) {
+    if (args.workspaceId !== ctx.workspaceId) {
+        throw new ScopeViolationError({
+            requestedTenantId: args.workspaceId,
+            contextTenantId: ctx.workspaceId,
+            reason: "args.workspaceId does not match bearer-resolved context workspaceId",
+        });
+    }
+    return ctx.workspaceId;
+}
+// ---------------------------------------------------------------------------
+// decodeUnverifiedBearer
+// ---------------------------------------------------------------------------
+/**
+ * @security ⚠️ DECODE-ONLY. NOT AUTHENTICATION. NOT A TRUST BOUNDARY.
+ *
+ * Decodes a `base64(JSON({ userId, workspaceId, roles[] }))` payload and
+ * validates its SHAPE with Zod. It performs NO signature verification, NO
+ * issuer check, NO expiry check, NO replay-attack protection. The decoded
+ * payload is attacker-controlled and MUST NOT be used as the source of
+ * truth for multi-tenant isolation.
+ *
+ * Forgery example: any attacker producing
+ *   base64(JSON({ userId:"x", workspaceId:"victim-org", roles:["Admin"] }))
+ * passes this function. Treating the returned `workspaceId` as authoritative
+ * — for example feeding it into `getEffectiveTenantId` as the trusted
+ * `ctx.workspaceId` — silently grants cross-tenant access.
+ *
+ * Use only as:
+ *   - test fixture / harness helper
+ *   - decoder for a bearer that was ALREADY verified by an upstream signed-JWT
+ *     middleware (the production trust boundary)
+ *
+ * For the production trust boundary, callers MUST substitute a signed JWT
+ * (planned export in 0.3.0) or an opaque-token lookup against a Convex
+ * tenancy table.
+ *
+ * Renamed from `resolveBearer` (0.2.0 pre-release) to make the lack of
+ * verification impossible to miss at the call-site.
+ */
+const bearerPayloadSchema = z.object({
+    userId: z.string().min(1),
+    workspaceId: z.string().min(1),
+    roles: z.array(workspaceRoleSchema),
+});
+export async function decodeUnverifiedBearer(token) {
+    let raw;
+    try {
+        raw = Buffer.from(token, "base64").toString("utf-8");
+    }
+    catch {
+        throw new Error(`decodeUnverifiedBearer: failed to base64-decode token`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`decodeUnverifiedBearer: token payload is not valid JSON`);
+    }
+    // Zod parse — throws ZodError on schema violations (missing fields, bad roles).
+    return bearerPayloadSchema.parse(parsed);
+}
+//# sourceMappingURL=tenancy-domain.js.map

package/dist/tenancy-domain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenancy-domain.js","sourceRoot":"","sources":["../src/tenancy-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGzE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AAGH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,IAAI,EAAE,mBAAmB;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC;AAGH,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;CACpC,CAAC,CAAC;AAaH;;;;;;GAMG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,iBAA0B,CAAC;IAClC,OAAO,CAAwB;IAExC,YAAY,OAA8B;QACxC,KAAK,CACH,sCAAsC,OAAO,CAAC,iBAAiB,oCAAoC,OAAO,CAAC,eAAe,OAAO,OAAO,CAAC,MAAM,EAAE,CAClJ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,kFAAkF;QAClF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAkB,EAClB,IAA6B;IAE7B,IAAI,IAAI,CAAC,WAAW,KAAK,GAAG,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,IAAI,mBAAmB,CAAC;YAC5B,iBAAiB,EAAE,IAAI,CAAC,WAAW;YACnC,eAAe,EAAE,GAAG,CAAC,WAAW;YAChC,MAAM,EAAE,qEAAqE;SAC9E,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,WAAW,CAAC;AACzB,CAAC;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;CACpC,CAAC,CAAC;AAIH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,KAAa;IAEb,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,OAAO,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/cloud-identity",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud (multi-tenant MCP).",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,10 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js"
+    },
+    "./tenancy-domain": {
+      "types": "./dist/tenancy-domain.d.ts",
+      "import": "./dist/tenancy-domain.js"
     }
   },
   "files": [
@@ -68,5 +72,8 @@
     "@types/node": "^20.11.0",
     "typescript": "^5.4.0",
     "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
   }
 }