@vantageos/cloud-identity 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+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.1.0] - 2026-06-04
+
+Initial release.
+
+### Added
+- `crypto.timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean` — constant-time byte comparison with branch-timing-leak mitigation on length mismatch.
+- `scope-filter.passesScopeFilter / scopeFilterList / scopeFilterGet` — row-level visibility filter honouring `fromAllowList` + `namespaceReadPrefixes` with master pass-through and legacy-bearer back-compat.
+- `bearer-validation.validateMasterBearer` — `Authorization: Bearer <token>` parsing + sha256 constant-time match against a master secret.
+- Public type surface: `OAuthCtx`, `ScopeProfile`, `NamespacePrefix`, `FromAllowListEntry`, `ValidateMasterBearerResult`.
+
+### Notes
+- `getEffectiveWorkspaceId` deferred to 0.2.0 (depends on `vantageos-crm` workspace helper, owned by Theta).
+- No `provenance: true` in `publishConfig` — provenance only from CI per fleet friction lesson `npm-publish-provenance-only-from-ci-not-local-host`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VantagePeers Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @vantageos/cloud-identity
+
+Framework-agnostic identity + scope-filter primitives for **VantagePeers Cloud** (multi-tenant MCP).
+
+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.
+
+## Install
+
+```bash
+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 scope
+
+This release ships the **transport-agnostic** core:
+
+- `crypto.timingSafeEqual`
+- `scope-filter.{passesScopeFilter, scopeFilterList, scopeFilterGet}`
+- `bearer-validation.validateMasterBearer`
+- types
+
+## 0.2.0 roadmap
+
+- `getEffectiveWorkspaceId` (workspace resolution helper, sourced from `vantageos-crm`).
+- D1 ghost Clerk identity injection.
+- 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"],
+  namespaceWritePrefixes: [],
+};
+const visible = scopeFilterList(ctx, rowsFromConvex);
+```
+
+### Master Bearer validation
+
+```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 });
+}
+```
+
+## Security doctrine
+
+Canonical reference: `docs/cloud/security-multi-tenant.md` in the `vantage-peers` repo.
+
+## License
+
+MIT — VantagePeers Cloud, 2026.

package/dist/bearer-validation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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:
+ *   - 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
+ *     compare which is non-constant-time. This brick fixes that leak so any
+ *     caller using `validateMasterBearer` inherits the safer behaviour.
+ *
+ * Surface:
+ *   `validateMasterBearer(authHeader, masterSecret) → ValidateMasterBearerResult`
+ *
+ * Errors are coarse-grained on purpose — callers should not surface the exact
+ * reason to remote clients beyond a generic 401/403.
+ */
+import type { ValidateMasterBearerResult } from "./types.js";
+/**
+ * Validate an `Authorization: Bearer <token>` header against a configured
+ * master secret.
+ *
+ *   - missing header  → `{ok: false, error: "missing"}`
+ *   - bad format / empty token / empty secret → `{ok: false, error: "malformed"}`
+ *   - token sha256 != master sha256 (constant-time) → `{ok: false, error: "mismatch"}`
+ *   - match → `{ok: true}`
+ *
+ * The scheme prefix match is case-insensitive (RFC 7235 §2.1) but the token
+ * itself is treated as opaque bytes.
+ */
+export declare function validateMasterBearer(authHeader: string | undefined, masterSecret: string): Promise<ValidateMasterBearerResult>;
+//# sourceMappingURL=bearer-validation.d.ts.map

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

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

package/dist/bearer-validation.js

@@ -0,0 +1,61 @@
+/**
+ * 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:
+ *   - 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
+ *     compare which is non-constant-time. This brick fixes that leak so any
+ *     caller using `validateMasterBearer` inherits the safer behaviour.
+ *
+ * Surface:
+ *   `validateMasterBearer(authHeader, masterSecret) → ValidateMasterBearerResult`
+ *
+ * Errors are coarse-grained on purpose — callers should not surface the exact
+ * reason to remote clients beyond a generic 401/403.
+ */
+import { timingSafeEqual } from "./crypto.js";
+const BEARER_PREFIX_LOWER = "bearer ";
+async function sha256Bytes(input) {
+    const data = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return new Uint8Array(digest);
+}
+/**
+ * Validate an `Authorization: Bearer <token>` header against a configured
+ * master secret.
+ *
+ *   - missing header  → `{ok: false, error: "missing"}`
+ *   - bad format / empty token / empty secret → `{ok: false, error: "malformed"}`
+ *   - token sha256 != master sha256 (constant-time) → `{ok: false, error: "mismatch"}`
+ *   - match → `{ok: true}`
+ *
+ * The scheme prefix match is case-insensitive (RFC 7235 §2.1) but the token
+ * itself is treated as opaque bytes.
+ */
+export async function validateMasterBearer(authHeader, masterSecret) {
+    if (authHeader === undefined || authHeader === null || authHeader === "") {
+        return { ok: false, error: "missing" };
+    }
+    if (!masterSecret || masterSecret.length === 0) {
+        return { ok: false, error: "malformed" };
+    }
+    // Case-insensitive scheme match without lower-casing the token bytes.
+    const lower = authHeader.toLowerCase();
+    if (!lower.startsWith(BEARER_PREFIX_LOWER)) {
+        return { ok: false, error: "malformed" };
+    }
+    const token = authHeader.slice(BEARER_PREFIX_LOWER.length).trim();
+    if (token.length === 0) {
+        return { ok: false, error: "malformed" };
+    }
+    const [tokenDigest, secretDigest] = await Promise.all([
+        sha256Bytes(token),
+        sha256Bytes(masterSecret),
+    ]);
+    const ok = await timingSafeEqual(tokenDigest, secretDigest);
+    return ok ? { ok: true } : { ok: false, error: "mismatch" };
+}
+//# sourceMappingURL=bearer-validation.js.map

package/dist/bearer-validation.js.map

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

package/dist/crypto.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.).
+ *
+ * Algorithm (identical to source):
+ *   1. Length mismatch → still run a dummy Web Crypto HMAC over equal-length
+ *      input to avoid a branch-timing leak, then return false.
+ *   2. Equal length → XOR-accumulate diff across all bytes, return diff === 0.
+ *
+ * Web Crypto (`crypto.subtle`) is used for the dummy work (not Node's
+ * `crypto.timingSafeEqual`) for portability across runtimes (Node 20+, Bun,
+ * Deno, edge runtimes) and parity with the original Convex implementation.
+ */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): Promise<boolean>;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

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

package/dist/crypto.js

@@ -0,0 +1,34 @@
+/**
+ * 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.).
+ *
+ * Algorithm (identical to source):
+ *   1. Length mismatch → still run a dummy Web Crypto HMAC over equal-length
+ *      input to avoid a branch-timing leak, then return false.
+ *   2. Equal length → XOR-accumulate diff across all bytes, return diff === 0.
+ *
+ * Web Crypto (`crypto.subtle`) is used for the dummy work (not Node's
+ * `crypto.timingSafeEqual`) for portability across runtimes (Node 20+, Bun,
+ * Deno, edge runtimes) and parity with the original Convex implementation.
+ */
+export async function timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+        // Still do a comparison on equal-length buffers to avoid branch-timing leak.
+        const dummy = new Uint8Array(a.length);
+        const keyMaterial = a.length > 0 ? a : new Uint8Array([0]);
+        const aKey = await crypto.subtle.importKey("raw", keyMaterial, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        await crypto.subtle.sign("HMAC", aKey, dummy);
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @vantageos/cloud-identity — public surface.
+ *
+ * Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud
+ * (multi-tenant MCP). Consumed by `vantage-peers-mcp` and
+ * `@vantageos/vantage-crm-mcp`.
+ */
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @vantageos/cloud-identity — public surface.
+ *
+ * Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud
+ * (multi-tenant MCP). Consumed by `vantage-peers-mcp` and
+ * `@vantageos/vantage-crm-mcp`.
+ */
+export { timingSafeEqual } from "./crypto.js";
+export { passesScopeFilter, scopeFilterList, scopeFilterGet, isMasterScope, isWildcardScope, } from "./scope-filter.js";
+export { validateMasterBearer } from "./bearer-validation.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/scope-filter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Sprint S3.1 B2 — scope-aware filter helpers for VP MCP tools.
+ *
+ * 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`.
+ *
+ * Doctrine references:
+ *   - decisions/doctrine-scope-aware-filter-2026-05-26.md (D3 base)
+ *   - memory j579y6f31g7xzgtgdnpgetdmjx87ztyj (D9-D14 extension)
+ *
+ * Contract:
+ *   - 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
+ *       row.namespace startsWith one of oauthCtx.namespaceReadPrefixes
+ *           (prefix matched as exact-equal OR followed by '/' boundary)
+ *   - Row missing BOTH `createdBy` and `namespace` = denied for non-master.
+ *
+ * NOTE: this module is intentionally framework-agnostic — no McpServer / Hono
+ * imports — to keep the helpers trivially unit-testable.
+ */
+import type { OAuthCtx } from "./types.js";
+/**
+ * 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.
+ */
+export type ScopeFilterable = {
+    createdBy?: string;
+    namespace?: string;
+};
+/**
+ * Returns true when the scope profile grants full, wildcard access.
+ * Mirrors `isMasterScope` from the source module: `scope === "master"` OR
+ * `fromAllowList` contains the `"*"` sentinel.
+ */
+export declare function isMasterScope(ctx: OAuthCtx | undefined): 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
+ *
+ * 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;
+/**
+ * Filter a list of rows (post-query). Used by list_* tools.
+ */
+export declare function scopeFilterList<T extends ScopeFilterable>(oauthCtx: OAuthCtx | undefined, 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;
+/**
+ * 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;
+//# sourceMappingURL=scope-filter.d.ts.map

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

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

package/dist/scope-filter.js

@@ -0,0 +1,95 @@
+/**
+ * Sprint S3.1 B2 — scope-aware filter helpers for VP MCP tools.
+ *
+ * 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`.
+ *
+ * Doctrine references:
+ *   - decisions/doctrine-scope-aware-filter-2026-05-26.md (D3 base)
+ *   - memory j579y6f31g7xzgtgdnpgetdmjx87ztyj (D9-D14 extension)
+ *
+ * Contract:
+ *   - 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
+ *       row.namespace startsWith one of oauthCtx.namespaceReadPrefixes
+ *           (prefix matched as exact-equal OR followed by '/' boundary)
+ *   - Row missing BOTH `createdBy` and `namespace` = denied for non-master.
+ *
+ * NOTE: this module is intentionally framework-agnostic — no McpServer / Hono
+ * imports — to keep the helpers trivially unit-testable.
+ */
+/**
+ * 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;
+    if (ctx.scope === "master")
+        return true;
+    return ctx.fromAllowList.includes("*");
+}
+/**
+ * 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
+ *
+ * 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;
+    if (isMasterScope(oauthCtx))
+        return true;
+    const { createdBy, namespace } = row;
+    if (createdBy && oauthCtx.fromAllowList.includes(createdBy))
+        return true;
+    if (namespace) {
+        for (const p of oauthCtx.namespaceReadPrefixes) {
+            if (namespace === p)
+                return true;
+            if (namespace.startsWith(`${p}/`))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Filter a list of rows (post-query). Used by list_* tools.
+ */
+export function scopeFilterList(oauthCtx, rows) {
+    return rows.filter((r) => passesScopeFilter(oauthCtx, r));
+}
+/**
+ * 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 function scopeFilterGet(oauthCtx, row) {
+    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;
+    return isMasterScope(ctx);
+}
+//# sourceMappingURL=scope-filter.js.map

package/dist/scope-filter.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Public type surface for @vantageos/cloud-identity.
+ *
+ * Framework-agnostic — no Hono, no Convex, no MCP SDK imports.
+ */
+/**
+ * Scope profile name. Master = wildcard. Tenant = scoped via fromAllowList
+ * and namespace prefixes. Extensible string for future profiles.
+ */
+export type ScopeProfile = "master" | "tenant" | (string & {});
+/**
+ * Namespace prefix (matched as exact-equal OR followed by '/' boundary).
+ */
+export type NamespacePrefix = string;
+/**
+ * Identifier allowed on a row's `createdBy` field for non-master scopes.
+ */
+export type FromAllowListEntry = string;
+/**
+ * Minimal OAuth context attached to an inbound MCP request.
+ *
+ * - `fromAllowList`: row.createdBy must be in this list for non-master callers
+ *   to see a row. `["*"]` is the master wildcard convention.
+ * - `namespaceReadPrefixes`: row.namespace must equal one of these OR start
+ *   with prefix + '/' for the row to be readable by non-master callers.
+ * - `namespaceWritePrefixes`: same semantics for write paths (enforced by the
+ *   caller, this brick only exposes the field on the type).
+ * - `scope`: optional scope profile name. `"master"` triggers wildcard pass.
+ */
+export type OAuthCtx = {
+    fromAllowList: FromAllowListEntry[];
+    namespaceReadPrefixes: NamespacePrefix[];
+    namespaceWritePrefixes: NamespacePrefix[];
+    scope?: ScopeProfile;
+};
+/**
+ * Result of `validateMasterBearer`.
+ *
+ * - `ok: true` → token matched master secret in constant time.
+ * - `ok: false` with `error: "missing"` → no Authorization header.
+ * - `ok: false` with `error: "malformed"` → header present but not parseable
+ *   as `Bearer <non-empty-token>`, OR master secret is empty.
+ * - `ok: false` with `error: "mismatch"` → token parsed but did not match.
+ */
+export type ValidateMasterBearerResult = {
+    ok: true;
+    error?: undefined;
+} | {
+    ok: false;
+    error: "missing" | "malformed" | "mismatch";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,qBAAqB,EAAE,eAAe,EAAE,CAAC;IACzC,sBAAsB,EAAE,eAAe,EAAE,CAAC;IAC1C,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,0BAA0B,GAClC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,CAAA;CAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public type surface for @vantageos/cloud-identity.
+ *
+ * Framework-agnostic — no Hono, no Convex, no MCP SDK imports.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@vantageos/cloud-identity",
+  "version": "0.1.0",
+  "description": "Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud (multi-tenant MCP).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./crypto": {
+      "types": "./dist/crypto.d.ts",
+      "import": "./dist/crypto.js"
+    },
+    "./scope-filter": {
+      "types": "./dist/scope-filter.d.ts",
+      "import": "./dist/scope-filter.js"
+    },
+    "./bearer-validation": {
+      "types": "./dist/bearer-validation.d.ts",
+      "import": "./dist/bearer-validation.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "vantagepeers",
+    "mcp",
+    "oauth",
+    "scope",
+    "multi-tenant",
+    "identity"
+  ],
+  "author": "VantagePeers Cloud",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vantageos-agency/cloud-identity.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vantageos-agency/cloud-identity/issues"
+  },
+  "homepage": "https://github.com/vantageos-agency/cloud-identity#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}