@vantageos/cloud-identity 0.1.0 → 0.3.0

package/dist/org-guard.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @vantageos/cloud-identity — Organization-membership guard.
+ * (See package.json "version" for the release this shipped in.)
+ *
+ * Closes the second measured 0.2.0 defect: the published package exposed no
+ * "must belong to an organization" gate anywhere (`grep -rlE
+ * "requireOrg|orgRequired|orgId" package/dist/*.js` returned no matches on
+ * the 0.2.0 tarball). Absence of an organization must REFUSE, never fall
+ * through to full access — the same defect class as the scope-filter fix in
+ * `./scope-filter.ts`.
+ *
+ * The semantics are reused verbatim from a Convex implementation of the same
+ * guard rather than reinvented — a second implementation of one authorization
+ * check is a second chance to get it wrong. That original:
+ *
+ *   - takes a Convex `QueryCtx | MutationCtx | ActionCtx`
+ *   - derives identity via `ctx.auth.getUserIdentity()`
+ *   - throws when there is no session
+ *   - throws when `identity.org_id` is not a non-empty string
+ *   - returns the org id
+ *
+ * ADAPTATION (named per the brief's requirement to flag any semantic
+ * deviation): this package is framework-agnostic and has no `ctx.auth`. The
+ * caller pre-resolves whichever identity/bearer object it already has
+ * (Clerk session identity for the human path, or the package's own
+ * `TenantContext` — see `./tenancy-domain.ts` — for the machine/bearer path)
+ * and passes it in as a `TenantSource`. The refuse-on-absence /
+ * refuse-on-empty semantics are otherwise identical to the source function;
+ * no other behavioural change was made.
+ *
+ * This is the membership half of the package's contract; tenant resolution,
+ * row filtering and identifier validation are covered by
+ * `getEffectiveTenantId`, `passesScopeFilter`/`scopeFilterList` and
+ * `validateMasterBearer` respectively. Framework adapters wrap
+ * `requireTenantId`; they must never reimplement its checks.
+ */
+import type { TenantContext } from "./tenancy-domain.js";
+/**
+ * Minimal shape of a resolved human-path session identity. Intentionally
+ * framework-agnostic: the caller derives this from Clerk (or any other
+ * session provider) before calling `requireTenantId` — this package never
+ * imports a session SDK.
+ */
+export type SessionIdentity = {
+    orgId?: string | null;
+};
+/**
+ * Discriminated union covering both VantagePeers Cloud entry paths behind
+ * one contract:
+ *   - `session`: human path, via a connection/login provider (Clerk, etc.).
+ *   - `bearer`: machine path, via a resolved, ALREADY-VERIFIED token
+ *     (`TenantContext` — see `decodeUnverifiedBearer` / the planned signed-JWT
+ *     verifier for how a `TenantContext` gets produced).
+ */
+export type TenantSource = {
+    kind: "session";
+    identity: SessionIdentity | null | undefined;
+} | {
+    kind: "bearer";
+    context: TenantContext;
+};
+/**
+ * Resolve the caller's tenant id, refusing when no organization/workspace is
+ * attached — for EITHER entry path, behind one contract.
+ *
+ *   - `kind: "session"` and `identity` is null/undefined → throws
+ *     ("Unauthenticated: no session.")
+ *   - `kind: "session"` and `identity.orgId` is missing or empty → throws
+ *     ("No active organization on this session...")
+ *   - `kind: "bearer"` and `context.workspaceId` is missing or empty → throws
+ *     ("No workspace on this bearer-resolved tenant context...")
+ *   - otherwise → returns the tenant id (orgId, or workspaceId)
+ *
+ * A right is never granted by absence: every branch above refuses by
+ * throwing, there is no fallback branch that returns a value when
+ * organization/workspace information is missing.
+ */
+export declare function requireTenantId(source: TenantSource): string;
+//# sourceMappingURL=org-guard.d.ts.map

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

@@ -0,0 +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"}

package/dist/org-guard.js

@@ -0,0 +1,70 @@
+/**
+ * @vantageos/cloud-identity — Organization-membership guard.
+ * (See package.json "version" for the release this shipped in.)
+ *
+ * Closes the second measured 0.2.0 defect: the published package exposed no
+ * "must belong to an organization" gate anywhere (`grep -rlE
+ * "requireOrg|orgRequired|orgId" package/dist/*.js` returned no matches on
+ * the 0.2.0 tarball). Absence of an organization must REFUSE, never fall
+ * through to full access — the same defect class as the scope-filter fix in
+ * `./scope-filter.ts`.
+ *
+ * The semantics are reused verbatim from a Convex implementation of the same
+ * guard rather than reinvented — a second implementation of one authorization
+ * check is a second chance to get it wrong. That original:
+ *
+ *   - takes a Convex `QueryCtx | MutationCtx | ActionCtx`
+ *   - derives identity via `ctx.auth.getUserIdentity()`
+ *   - throws when there is no session
+ *   - throws when `identity.org_id` is not a non-empty string
+ *   - returns the org id
+ *
+ * ADAPTATION (named per the brief's requirement to flag any semantic
+ * deviation): this package is framework-agnostic and has no `ctx.auth`. The
+ * caller pre-resolves whichever identity/bearer object it already has
+ * (Clerk session identity for the human path, or the package's own
+ * `TenantContext` — see `./tenancy-domain.ts` — for the machine/bearer path)
+ * and passes it in as a `TenantSource`. The refuse-on-absence /
+ * refuse-on-empty semantics are otherwise identical to the source function;
+ * no other behavioural change was made.
+ *
+ * This is the membership half of the package's contract; tenant resolution,
+ * row filtering and identifier validation are covered by
+ * `getEffectiveTenantId`, `passesScopeFilter`/`scopeFilterList` and
+ * `validateMasterBearer` respectively. Framework adapters wrap
+ * `requireTenantId`; they must never reimplement its checks.
+ */
+/**
+ * Resolve the caller's tenant id, refusing when no organization/workspace is
+ * attached — for EITHER entry path, behind one contract.
+ *
+ *   - `kind: "session"` and `identity` is null/undefined → throws
+ *     ("Unauthenticated: no session.")
+ *   - `kind: "session"` and `identity.orgId` is missing or empty → throws
+ *     ("No active organization on this session...")
+ *   - `kind: "bearer"` and `context.workspaceId` is missing or empty → throws
+ *     ("No workspace on this bearer-resolved tenant context...")
+ *   - otherwise → returns the tenant id (orgId, or workspaceId)
+ *
+ * A right is never granted by absence: every branch above refuses by
+ * throwing, there is no fallback branch that returns a value when
+ * organization/workspace information is missing.
+ */
+export function requireTenantId(source) {
+    if (source.kind === "session") {
+        if (!source.identity) {
+            throw new Error("Unauthenticated: no session.");
+        }
+        const orgId = source.identity.orgId;
+        if (typeof orgId !== "string" || orgId.length === 0) {
+            throw new Error("No active organization on this session: select an organization before accessing agents.");
+        }
+        return orgId;
+    }
+    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.");
+    }
+    return workspaceId;
+}
+//# sourceMappingURL=org-guard.js.map

package/dist/org-guard.js.map

@@ -0,0 +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"}

package/dist/scope-filter.d.ts

@@ -1,18 +1,24 @@
 /**
- * Sprint S3.1 B2 — scope-aware filter helpers for VP MCP tools.
+ * Scope-aware row filter.
  *
- * Ported from `vantage-memory/mcp-server/src/scope-filter.ts`. Behaviour is
- * preserved verbatim; only the type dependency on the in-tree `OAuthContext`
- * is replaced by the framework-agnostic `OAuthCtx` from `./types`.
+ * The behaviour was preserved verbatim from an earlier in-tree
+ * implementation; the only change was replacing a framework-specific context
+ * type with the framework-agnostic `OAuthCtx` from `./types`.
  *
- * Doctrine references:
- *   - decisions/doctrine-scope-aware-filter-2026-05-26.md (D3 base)
- *   - memory j579y6f31g7xzgtgdnpgetdmjx87ztyj (D9-D14 extension)
- *
- * Contract:
+ * Contract (0.3.0 — BREAKING vs. 0.2.0):
+ *   - `oauthCtx` is now MANDATORY. A right is never granted by absence: the
+ *     0.2.0 behaviour of `oauthCtx === undefined` silently passing everything
+ *     (as if the caller were master-scoped) was the exact defect class this
+ *     release closes. Every exported function below now requires `OAuthCtx`
+ *     at the type level — an omitted argument breaks the caller's build,
+ *     it never falls through to a more permissive runtime path.
+ *   - Callers that genuinely need the old legacy-bearer wildcard behaviour
+ *     MUST import and pass `LEGACY_WILDCARD_CTX` explicitly — the compat
+ *     path is requested by name, never inferred from a missing argument.
+ *   - As defense-in-depth against callers that bypass the type system
+ *     (untyped JS, `as any`), every function also throws at runtime if
+ *     `oauthCtx` is nullish, instead of silently granting access.
  *   - Master scope (scope === "master" OR fromAllowList includes "*") = wildcard pass.
- *   - Legacy bearer (oauthCtx === undefined) = wildcard pass (treated as master-
- *     equivalent for backward-compatibility with mcpTenants Pi/Tau/Phi paths).
  *   - Non-master scope = row passes iff:
  *       row.createdBy ∈ oauthCtx.fromAllowList
  *       OR
@@ -24,6 +30,12 @@
  * imports — to keep the helpers trivially unit-testable.
  */
 import type { OAuthCtx } from "./types.js";
+/**
+ * Explicit legacy-compat sentinel. Passing this constant reproduces the
+ * pre-0.3.0 "no oauthCtx" wildcard behaviour — but the caller must import
+ * and pass it BY NAME. It is never inferred from an omitted argument.
+ */
+export declare const LEGACY_WILDCARD_CTX: OAuthCtx;
 /**
  * Row shape accepted by the scope filter. All fields optional because real
  * Convex documents from list_peers / list_messages / etc. don't all carry both.
@@ -37,35 +49,38 @@ export type ScopeFilterable = {
  * Mirrors `isMasterScope` from the source module: `scope === "master"` OR
  * `fromAllowList` contains the `"*"` sentinel.
  */
-export declare function isMasterScope(ctx: OAuthCtx | undefined): boolean;
+export declare function isMasterScope(ctx: OAuthCtx): boolean;
 /**
  * Core predicate. Returns true when the row is visible to the caller.
  *
  *   - Master scope (isMasterScope === true)            → true (wildcard)
- *   - Legacy bearer (oauthCtx === undefined)           → true (back-compat)
  *   - row.createdBy ∈ oauthCtx.fromAllowList           → true
  *   - row.namespace === prefix OR startsWith prefix+'/'
  *     for any prefix ∈ oauthCtx.namespaceReadPrefixes  → true
  *   - otherwise                                        → false
  *
+ * `oauthCtx` is mandatory (see module-level contract note above): an omitted
+ * argument throws instead of silently granting wildcard access. Callers that
+ * need the old legacy-bearer wildcard behaviour must pass `LEGACY_WILDCARD_CTX`
+ * explicitly.
+ *
  * Substring matches that don't fall on a '/' boundary are explicitly rejected
  * (e.g. namespace="orchestrator/alphabet" does NOT match prefix
  * "orchestrator/alpha"). This avoids the classic prefix-isolation bypass.
  */
-export declare function passesScopeFilter(oauthCtx: OAuthCtx | undefined, row: ScopeFilterable): boolean;
+export declare function passesScopeFilter(oauthCtx: OAuthCtx, row: ScopeFilterable): boolean;
 /**
  * Filter a list of rows (post-query). Used by list_* tools.
  */
-export declare function scopeFilterList<T extends ScopeFilterable>(oauthCtx: OAuthCtx | undefined, rows: T[]): T[];
+export declare function scopeFilterList<T extends ScopeFilterable>(oauthCtx: OAuthCtx, rows: T[]): T[];
 /**
  * Assert a single row passes (get_* tools). Returns the row when allowed, null
  * otherwise — callers translate null to a 404-equivalent "not found" MCP error
  * to avoid leaking the difference between "absent" and "filtered out".
  */
-export declare function scopeFilterGet<T extends ScopeFilterable>(oauthCtx: OAuthCtx | undefined, row: T | null | undefined): T | null;
+export declare function scopeFilterGet<T extends ScopeFilterable>(oauthCtx: OAuthCtx, row: T | null | undefined): T | null;
 /**
  * Helper for callers that want a single "is master / legacy" predicate.
- * Mirrors the legacy-bearer-passes-through convention.
  */
-export declare function isWildcardScope(ctx: OAuthCtx | undefined): boolean;
+export declare function isWildcardScope(ctx: OAuthCtx): boolean;
 //# sourceMappingURL=scope-filter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scope-filter.d.ts","sourceRoot":"","sources":["../src/scope-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAIhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,GAAG,EAAE,eAAe,GACnB,OAAO,CAYT;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,IAAI,EAAE,CAAC,EAAE,GACR,CAAC,EAAE,CAEL;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EACtD,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACxB,CAAC,GAAG,IAAI,CAGV;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAGlE"}
+{"version":3,"file":"scope-filter.d.ts","sourceRoot":"","sources":["../src/scope-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAKjC,CAAC;AAWF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAIpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,eAAe,GACnB,OAAO,CAYT;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,CAAC,EAAE,GACR,CAAC,EAAE,CAGL;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EACtD,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACxB,CAAC,GAAG,IAAI,CAIV;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAGtD"}

package/dist/scope-filter.js

@@ -1,18 +1,24 @@
 /**
- * Sprint S3.1 B2 — scope-aware filter helpers for VP MCP tools.
+ * Scope-aware row filter.
  *
- * Ported from `vantage-memory/mcp-server/src/scope-filter.ts`. Behaviour is
- * preserved verbatim; only the type dependency on the in-tree `OAuthContext`
- * is replaced by the framework-agnostic `OAuthCtx` from `./types`.
+ * The behaviour was preserved verbatim from an earlier in-tree
+ * implementation; the only change was replacing a framework-specific context
+ * type with the framework-agnostic `OAuthCtx` from `./types`.
  *
- * Doctrine references:
- *   - decisions/doctrine-scope-aware-filter-2026-05-26.md (D3 base)
- *   - memory j579y6f31g7xzgtgdnpgetdmjx87ztyj (D9-D14 extension)
- *
- * Contract:
+ * Contract (0.3.0 — BREAKING vs. 0.2.0):
+ *   - `oauthCtx` is now MANDATORY. A right is never granted by absence: the
+ *     0.2.0 behaviour of `oauthCtx === undefined` silently passing everything
+ *     (as if the caller were master-scoped) was the exact defect class this
+ *     release closes. Every exported function below now requires `OAuthCtx`
+ *     at the type level — an omitted argument breaks the caller's build,
+ *     it never falls through to a more permissive runtime path.
+ *   - Callers that genuinely need the old legacy-bearer wildcard behaviour
+ *     MUST import and pass `LEGACY_WILDCARD_CTX` explicitly — the compat
+ *     path is requested by name, never inferred from a missing argument.
+ *   - As defense-in-depth against callers that bypass the type system
+ *     (untyped JS, `as any`), every function also throws at runtime if
+ *     `oauthCtx` is nullish, instead of silently granting access.
  *   - Master scope (scope === "master" OR fromAllowList includes "*") = wildcard pass.
- *   - Legacy bearer (oauthCtx === undefined) = wildcard pass (treated as master-
- *     equivalent for backward-compatibility with mcpTenants Pi/Tau/Phi paths).
  *   - Non-master scope = row passes iff:
  *       row.createdBy ∈ oauthCtx.fromAllowList
  *       OR
@@ -23,14 +29,30 @@
  * NOTE: this module is intentionally framework-agnostic — no McpServer / Hono
  * imports — to keep the helpers trivially unit-testable.
  */
+/**
+ * Explicit legacy-compat sentinel. Passing this constant reproduces the
+ * pre-0.3.0 "no oauthCtx" wildcard behaviour — but the caller must import
+ * and pass it BY NAME. It is never inferred from an omitted argument.
+ */
+export const LEGACY_WILDCARD_CTX = {
+    scope: "master",
+    fromAllowList: ["*"],
+    namespaceReadPrefixes: [],
+    namespaceWritePrefixes: [],
+};
+function assertOauthCtx(oauthCtx) {
+    if (oauthCtx == null) {
+        throw new TypeError("oauthCtx is required — pass an explicit OAuthCtx, or LEGACY_WILDCARD_CTX " +
+            "if you deliberately want the pre-0.3.0 legacy-bearer wildcard behaviour.");
+    }
+}
 /**
  * Returns true when the scope profile grants full, wildcard access.
  * Mirrors `isMasterScope` from the source module: `scope === "master"` OR
  * `fromAllowList` contains the `"*"` sentinel.
  */
 export function isMasterScope(ctx) {
-    if (!ctx)
-        return false;
+    assertOauthCtx(ctx);
     if (ctx.scope === "master")
         return true;
     return ctx.fromAllowList.includes("*");
@@ -39,19 +61,22 @@ export function isMasterScope(ctx) {
  * Core predicate. Returns true when the row is visible to the caller.
  *
  *   - Master scope (isMasterScope === true)            → true (wildcard)
- *   - Legacy bearer (oauthCtx === undefined)           → true (back-compat)
  *   - row.createdBy ∈ oauthCtx.fromAllowList           → true
  *   - row.namespace === prefix OR startsWith prefix+'/'
  *     for any prefix ∈ oauthCtx.namespaceReadPrefixes  → true
  *   - otherwise                                        → false
  *
+ * `oauthCtx` is mandatory (see module-level contract note above): an omitted
+ * argument throws instead of silently granting wildcard access. Callers that
+ * need the old legacy-bearer wildcard behaviour must pass `LEGACY_WILDCARD_CTX`
+ * explicitly.
+ *
  * Substring matches that don't fall on a '/' boundary are explicitly rejected
  * (e.g. namespace="orchestrator/alphabet" does NOT match prefix
  * "orchestrator/alpha"). This avoids the classic prefix-isolation bypass.
  */
 export function passesScopeFilter(oauthCtx, row) {
-    if (!oauthCtx)
-        return true;
+    assertOauthCtx(oauthCtx);
     if (isMasterScope(oauthCtx))
         return true;
     const { createdBy, namespace } = row;
@@ -71,6 +96,7 @@ export function passesScopeFilter(oauthCtx, row) {
  * Filter a list of rows (post-query). Used by list_* tools.
  */
 export function scopeFilterList(oauthCtx, rows) {
+    assertOauthCtx(oauthCtx);
     return rows.filter((r) => passesScopeFilter(oauthCtx, r));
 }
 /**
@@ -79,17 +105,16 @@ export function scopeFilterList(oauthCtx, rows) {
  * to avoid leaking the difference between "absent" and "filtered out".
  */
 export function scopeFilterGet(oauthCtx, row) {
+    assertOauthCtx(oauthCtx);
     if (row == null)
         return null;
     return passesScopeFilter(oauthCtx, row) ? row : null;
 }
 /**
  * Helper for callers that want a single "is master / legacy" predicate.
- * Mirrors the legacy-bearer-passes-through convention.
  */
 export function isWildcardScope(ctx) {
-    if (!ctx)
-        return true;
+    assertOauthCtx(ctx);
     return isMasterScope(ctx);
 }
 //# sourceMappingURL=scope-filter.js.map

package/dist/scope-filter.js.map

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

package/dist/tenancy-domain.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @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 before treating the payload as a
+ *     trust boundary.
+ */
+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
+ * verifier (not yet exported by this package) 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;;;;;;;;;;;;;;;;GAgBG;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"}