@vellumai/assistant 0.12.6-dev.202609301018.08b7375 → 0.12.6-dev.202609301115.aafbefc

package/ARCHITECTURE.md

@@ -83,6 +83,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 | Profile              | Scopes                                                                                                                                                | Used by                                      |
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
 | `actor_client_v1`    | `chat.{read,write}`, `approval.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `calls.{read,write}`, `feature_flags.{read,write}` | Desktop, CLI clients                         |
+| `contact_client_v1`  | `chat.write`, `approval.write`, `attachments.write`                                                                                                   | Non-guardian contact clients                 |
 | `gateway_ingress_v1` | `ingress.write`, `internal.write`                                                                                                                     | Gateway channel inbound + webhook forwarding |
 | `gateway_service_v1` | `chat.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `internal.write`                                                            | Gateway service-to-daemon calls              |
 | `local_v1`           | `local.all`                                                                                                                                           | Local (loopback) conversation sessions       |
@@ -98,6 +99,8 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 3. **Local identity** — Local connections use deterministic identity resolution without tokens.
 
+**Token role:** Each access and refresh token records the principal it belongs to, `guardian` or `contact`. The role picks the scope profile at mint time, and rotation carries it forward.
+
 **Route policy enforcement:** Every protected endpoint declares required scopes and allowed principal types in `src/runtime/auth/route-policy.ts`. The `enforcePolicy()` function checks the AuthContext against these requirements and returns 403 when access is denied. A guard test ensures every dispatched endpoint has a corresponding policy entry.
 
 **Credential storage:** Only hashed tokens are persisted. Access token hashes go in `credential_records`; refresh token hashes in `refresh_token_records`. Raw tokens are returned once and never stored server-side.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.6-dev.202609301018.08b7375",
+  "version": "0.12.6-dev.202609301115.aafbefc",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/runtime/auth/__tests__/guard-tests.test.ts

@@ -8,13 +8,15 @@
  * 2. No X-Actor-Token references in production code.
  * 3. No legacy gateway-origin proof in production code.
  * 4. Scope profile contract — every profile resolves to the expected scopes.
+ * 5. Contact profile agreement: the gateway mints what this runtime honors.
  */
 
 import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { describe, expect, test } from "bun:test";
 
-import { resolveScopeProfile } from "../scopes.js";
+import { isNarrowScopeProfile, resolveScopeProfile } from "../scopes.js";
 import type { Scope, ScopeProfile } from "../types.js";
 
 // ---------------------------------------------------------------------------
@@ -253,6 +255,7 @@ describe("scope profile contract", () => {
       "feature_flags.read",
       "feature_flags.write",
     ],
+    contact_client_v1: ["chat.write", "approval.write", "attachments.write"],
     gateway_ingress_v1: ["ingress.write", "internal.write"],
     gateway_service_v1: [
       "chat.read",
@@ -290,3 +293,50 @@ describe("scope profile contract", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// 5. Contact profile agreement with the gateway
+//
+// The gateway mints `contact_client_v1` and this runtime decides what it may
+// reach. The two registries are separate tables, so a contact token carries
+// whichever scopes the narrower one grants: a scope missing here 403s a route
+// the gateway believes it opened.
+// ---------------------------------------------------------------------------
+
+describe("contact_client_v1 agrees with the gateway registry", () => {
+  const GATEWAY_SCOPES_PATH = resolve(
+    PROJECT_ROOT,
+    "gateway/src/auth/scopes.ts",
+  );
+
+  function gatewaySource(): string {
+    return readFileSync(GATEWAY_SCOPES_PATH, "utf8");
+  }
+
+  test("grants the same scopes on both sides", () => {
+    const block = /contact_client_v1: new Set<Scope>\(\[([^\]]*)\]\)/.exec(
+      gatewaySource(),
+    );
+    expect(
+      block,
+      `contact_client_v1 not found in ${GATEWAY_SCOPES_PATH}`,
+    ).not.toBeNull();
+
+    const gatewayScopes = [...block![1].matchAll(/"([^"]+)"/g)]
+      .map((m) => m[1])
+      .sort();
+    const runtimeScopes: string[] = [
+      ...resolveScopeProfile("contact_client_v1"),
+    ].sort();
+
+    expect(gatewayScopes.length).toBeGreaterThan(0);
+    expect(runtimeScopes).toEqual(gatewayScopes);
+  });
+
+  test("is narrow on both sides", () => {
+    const broad = /contact_client_v1: (true|false)/.exec(gatewaySource());
+    expect(broad).not.toBeNull();
+    expect(broad![1]).toBe("false");
+    expect(isNarrowScopeProfile("contact_client_v1")).toBe(true);
+  });
+});

package/src/runtime/auth/__tests__/scopes.test.ts

@@ -11,6 +11,7 @@ import type { AuthContext, Scope, ScopeProfile } from "../types.js";
 /** Every profile name; the Record keeps this list exhaustive. */
 const KNOWN_PROFILES = Object.keys({
   actor_client_v1: true,
+  contact_client_v1: true,
   gateway_ingress_v1: true,
   gateway_service_v1: true,
   local_v1: true,
@@ -129,6 +130,7 @@ describe("isNarrowScopeProfile", () => {
     // flipped onto a single-route grant would open every unscoped route to it.
     const narrow: Record<ScopeProfile, boolean> = {
       actor_client_v1: false,
+      contact_client_v1: true,
       gateway_ingress_v1: false,
       gateway_service_v1: false,
       local_v1: false,

package/src/runtime/auth/scopes.ts

@@ -27,6 +27,18 @@ const PROFILE_SCOPES: Record<ScopeProfile, ReadonlySet<Scope>> = {
     "feature_flags.read",
     "feature_flags.write",
   ]),
+  // A non-guardian principal. Excludes the settings, feature-flag and call
+  // scopes `actor_client_v1` carries: those reach the control plane, which
+  // only the guardian may write.
+  // Carries no read scope. The routes behind `chat.read`, `approval.read` and
+  // `attachments.read` take a caller-supplied conversation or attachment id
+  // and never check who is asking, so they return the guardian's data to any
+  // holder. Each read is added back once its routes filter by caller.
+  contact_client_v1: new Set<Scope>([
+    "chat.write",
+    "approval.write",
+    "attachments.write",
+  ]),
   gateway_ingress_v1: new Set<Scope>(["ingress.write", "internal.write"]),
   gateway_service_v1: new Set<Scope>([
     "chat.read",
@@ -91,6 +103,9 @@ export function hasAllScopes(ctx: AuthContext, ...scopes: Scope[]): boolean {
  */
 const BROAD_SCOPE_PROFILES: Record<ScopeProfile, boolean> = {
   actor_client_v1: true,
+  // Narrow: a route naming no scope is a route no one has judged a contact
+  // against, so it refuses them rather than admitting any valid token.
+  contact_client_v1: false,
   gateway_ingress_v1: true,
   gateway_service_v1: true,
   local_v1: true,

package/src/runtime/auth/types.ts

@@ -11,6 +11,7 @@
 
 export type ScopeProfile =
   | "actor_client_v1"
+  | "contact_client_v1"
   | "gateway_ingress_v1"
   | "gateway_service_v1"
   | "local_v1"