@withloops.ai/contracts 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from './events.ts';
 export * from './manifest.ts';
 export * from './api.ts';
 export * from './registry.ts';
+export * from './trust.ts';

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./events.js";
 export * from "./manifest.js";
 export * from "./api.js";
 export * from "./registry.js";
+export * from "./trust.js";

package/dist/manifest.d.ts

@@ -16,6 +16,7 @@ export declare const SyncAuth: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"oauth2">;
     authorizeUrl: z.ZodURL;
     tokenUrl: z.ZodURL;
+    clientId: z.ZodOptional<z.ZodString>;
     scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
     refresh: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
@@ -127,6 +128,7 @@ export declare const SyncManifest: z.ZodObject<{
         type: z.ZodLiteral<"oauth2">;
         authorizeUrl: z.ZodURL;
         tokenUrl: z.ZodURL;
+        clientId: z.ZodOptional<z.ZodString>;
         scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
         refresh: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
@@ -385,6 +387,7 @@ export declare const ManifestV1: z.ZodObject<{
             type: z.ZodLiteral<"oauth2">;
             authorizeUrl: z.ZodURL;
             tokenUrl: z.ZodURL;
+            clientId: z.ZodOptional<z.ZodString>;
             scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
             refresh: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{

package/dist/manifest.js

@@ -28,6 +28,8 @@ export const SyncAuth = z.discriminatedUnion('type', [
         type: z.literal('oauth2'),
         authorizeUrl: HttpsUrl,
         tokenUrl: HttpsUrl,
+        /** The developer's OAuth client id at their own service (public). The secret never goes in the manifest: it lives in the vault (APP_CLIENT_SECRET_REF). Added in 0.3.1. */
+        clientId: z.string().min(1).max(256).optional(),
         scopes: z.array(z.string().min(1)).default([]),
         refresh: z.boolean().default(true),
     }),

package/dist/registry.d.ts

@@ -74,6 +74,7 @@ export declare const AppVersionRecord: z.ZodObject<{
                 type: z.ZodLiteral<"oauth2">;
                 authorizeUrl: z.ZodURL;
                 tokenUrl: z.ZodURL;
+                clientId: z.ZodOptional<z.ZodString>;
                 scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
                 refresh: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>, z.ZodObject<{

package/dist/trust.d.ts

@@ -0,0 +1,206 @@
+import { z } from 'zod';
+import { AppRecord, Caller } from './registry.ts';
+/**
+ * Layer 1 (Trust): Loops as an OAuth provider, consent, the audit log, the developer switch and the apps vault.
+ * Skill devops-loops-developer-platform §1 (developer access), §6 (vault), §7 (OAuth both ways). Only ever ADD.
+ */
+/** The issuer. Discovery at `${LOOPS_OAUTH_ISSUER}/.well-known/oauth-authorization-server`. */
+export declare const LOOPS_OAUTH_ISSUER = "https://api.withloops.ai";
+export declare const OAUTH_PATHS: {
+    readonly authorize: "/oauth/authorize";
+    readonly token: "/oauth/token";
+    readonly register: "/oauth/register";
+};
+/** The `loops` CLI: a public client (PKCE, loopback redirect on 127.0.0.1, no secret). */
+export declare const LOOPS_CLI_CLIENT_ID = "loops-cli";
+/** The scope the CLI asks for: build, submit and dev-install apps as the signed-in developer. */
+export declare const DEVELOPER_SCOPE: "developer";
+export declare const OAuthClientRecord: z.ZodObject<{
+    clientId: z.ZodString;
+    appId: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    redirectUris: z.ZodArray<z.ZodString>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type OAuthClientRecord = z.infer<typeof OAuthClientRecord>;
+/** Returned ONCE when a client is minted (`loops create`); the registry keeps only a hash of the secret. */
+export declare const MintedClient: z.ZodObject<{
+    clientId: z.ZodString;
+    appId: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    redirectUris: z.ZodArray<z.ZodString>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    clientSecret: z.ZodString;
+}, z.core.$strip>;
+export type MintedClient = z.infer<typeof MintedClient>;
+export declare const CreateAppInput: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    redirectUris: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type CreateAppInput = z.infer<typeof CreateAppInput>;
+/** What a Loops access token stands for, resolved by the registry for backend-api `/v1`. */
+export declare const TokenCaller: z.ZodObject<{
+    caller: z.ZodObject<{
+        workspaceId: z.ZodString;
+        userId: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>;
+        developer: z.ZodBoolean;
+        superUser: z.ZodBoolean;
+    }, z.core.$strip>;
+    scopes: z.ZodArray<z.ZodString>;
+    clientId: z.ZodString;
+    appId: z.ZodNullable<z.ZodString>;
+    installId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type TokenCaller = z.infer<typeof TokenCaller>;
+/** One row per consent sheet answered: who approved which scopes for which version. */
+export declare const ConsentRecord: z.ZodObject<{
+    id: z.ZodString;
+    installId: z.ZodString;
+    appId: z.ZodString;
+    versionId: z.ZodString;
+    workspaceId: z.ZodString;
+    grantedBy: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "contacts:read": "contacts:read";
+        "contacts:write": "contacts:write";
+        "companies:read": "companies:read";
+        "companies:write": "companies:write";
+        "leads:read": "leads:read";
+        "leads:write": "leads:write";
+        "deals:read": "deals:read";
+        "deals:write": "deals:write";
+        "notes:write": "notes:write";
+        "actions:write": "actions:write";
+        "loops:read": "loops:read";
+        "loops:write": "loops:write";
+        "calls:read": "calls:read";
+        "meetings:read": "meetings:read";
+        "webhooks:manage": "webhooks:manage";
+    }>>;
+    consentedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ConsentRecord = z.infer<typeof ConsentRecord>;
+export declare const AuditEntry: z.ZodObject<{
+    id: z.ZodNumber;
+    at: z.ZodISODateTime;
+    actor: z.ZodString;
+    workspaceId: z.ZodNullable<z.ZodString>;
+    appId: z.ZodNullable<z.ZodString>;
+    versionId: z.ZodNullable<z.ZodString>;
+    installId: z.ZodNullable<z.ZodString>;
+    action: z.ZodString;
+    detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type AuditEntry = z.infer<typeof AuditEntry>;
+export declare const AuditQuery: z.ZodObject<{
+    appId: z.ZodOptional<z.ZodString>;
+    installId: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type AuditQuery = z.infer<typeof AuditQuery>;
+export declare const WorkspaceDeveloper: z.ZodObject<{
+    workspaceId: z.ZodString;
+    userId: z.ZodString;
+    grantedBy: z.ZodString;
+    grantedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type WorkspaceDeveloper = z.infer<typeof WorkspaceDeveloper>;
+/** `access_token`, `refresh_token`, `api_key`, `webhook_secret`… */
+export declare const SecretName: z.ZodString;
+export type SecretName = z.infer<typeof SecretName>;
+/** Where a secret belongs. All four parts are the encryption's additional data, so a copied row will not decrypt. */
+export declare const SecretRef: z.ZodObject<{
+    installId: z.ZodString;
+    workspaceId: z.ZodString;
+    appId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type SecretRef = z.infer<typeof SecretRef>;
+/**
+ * The developer's OAuth client secret for their own service is stored once per app under this reserved install id,
+ * in the app owner's workspace: `{ installId: APP_CLIENT_INSTALL_ID, workspaceId: app.ownerWorkspaceId, appId, name: 'oauth_client_secret' }`.
+ * Uninstall never deletes it; only deleting the app does. Added in 0.3.1.
+ */
+export declare const APP_CLIENT_INSTALL_ID: "ins_appclient";
+export declare const APP_CLIENT_SECRET_NAME: "oauth_client_secret";
+export declare function appClientSecretRef(appId: string, ownerWorkspaceId: string): SecretRef;
+/** Engine-side code exchange for an app connecting OUT (the handoff at api.thesoogroup.com/oauth/callback). Added in 0.3.1. */
+export declare const OAuthCodeExchange: z.ZodObject<{
+    install: z.ZodObject<{
+        workspaceId: z.ZodString;
+        installId: z.ZodString;
+        appId: z.ZodString;
+    }, z.core.$strip>;
+    ownerWorkspaceId: z.ZodString;
+    tokenUrl: z.ZodString;
+    clientId: z.ZodString;
+    code: z.ZodString;
+    codeVerifier: z.ZodOptional<z.ZodString>;
+    redirectUri: z.ZodString;
+}, z.core.$strip>;
+export type OAuthCodeExchange = z.infer<typeof OAuthCodeExchange>;
+/** What anyone outside the engine may see about a secret: never the value. */
+export declare const SecretInfo: z.ZodObject<{
+    name: z.ZodString;
+    keyVersion: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodISODateTime>;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type SecretInfo = z.infer<typeof SecretInfo>;
+/** `backend-apps-registry` default WorkerEntrypoint implements this as well as `RegistryRpc`. */
+export interface RegistryTrustRpc {
+    /** Create an app owned by the caller's workspace and mint its OAuth client (`loops create`). Developer only. */
+    createApp(caller: Caller, input: CreateAppInput): Promise<{
+        ok: true;
+        app: AppRecord;
+        client: MintedClient;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** Resolve a Loops OAuth access token (`Authorization: Bearer …`) for `/v1`; null when unknown, expired or revoked. */
+    resolveToken(bearer: string): Promise<TokenCaller | null>;
+    /** True when the user has the developer switch on in that workspace. */
+    isDeveloper(workspaceId: string, userId: string): Promise<boolean>;
+    /** Owner/Admin only. */
+    setDeveloper(caller: Caller, userId: string, on: boolean): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    listDevelopers(caller: Caller): Promise<WorkspaceDeveloper[]>;
+    /** Consents for one install of the caller's workspace, newest first. */
+    listConsents(caller: Caller, installId: string): Promise<ConsentRecord[]>;
+    /** Audit rows for the caller's workspace (SUPER sees all), newest first. */
+    listAudit(caller: Caller, query: AuditQuery): Promise<{
+        items: AuditEntry[];
+        nextCursor: string | null;
+    }>;
+}
+/** `backend-apps-engine` default WorkerEntrypoint implements this as well as `EngineRpc`. Values go in, never out. */
+export interface EngineVaultRpc {
+    putSecret(ref: SecretRef, value: string, expiresAt?: string | null): Promise<{
+        ok: true;
+    }>;
+    listSecrets(installId: string): Promise<SecretInfo[]>;
+    /** Uninstall calls this; returns how many rows went. */
+    deleteSecrets(installId: string): Promise<{
+        deleted: number;
+    }>;
+    /** Reads the app's client secret, POSTs to tokenUrl, stores access/refresh tokens for the install itself. Values never come back. Added in 0.3.1. */
+    exchangeOAuthCode(input: OAuthCodeExchange): Promise<{
+        ok: true;
+        expiresAt: string | null;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}

package/dist/trust.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { AppId, InstallId, Timestamp, UserId, VersionId, WorkspaceId } from "./ids.js";
+import { ScopeSchema } from "./scopes.js";
+import { AppRecord, Caller } from "./registry.js";
+/**
+ * Layer 1 (Trust): Loops as an OAuth provider, consent, the audit log, the developer switch and the apps vault.
+ * Skill devops-loops-developer-platform §1 (developer access), §6 (vault), §7 (OAuth both ways). Only ever ADD.
+ */
+// ── Loops as an OAuth provider (@cloudflare/workers-oauth-provider 1.x in backend-apps-registry) ──
+/** The issuer. Discovery at `${LOOPS_OAUTH_ISSUER}/.well-known/oauth-authorization-server`. */
+export const LOOPS_OAUTH_ISSUER = 'https://api.withloops.ai';
+export const OAUTH_PATHS = {
+    authorize: '/oauth/authorize',
+    token: '/oauth/token',
+    register: '/oauth/register',
+};
+/** The `loops` CLI: a public client (PKCE, loopback redirect on 127.0.0.1, no secret). */
+export const LOOPS_CLI_CLIENT_ID = 'loops-cli';
+/** The scope the CLI asks for: build, submit and dev-install apps as the signed-in developer. */
+export const DEVELOPER_SCOPE = 'developer';
+export const OAuthClientRecord = z.object({
+    clientId: z.string().min(8).max(128),
+    /** The app this client belongs to; null for first-party clients (the CLI). */
+    appId: AppId.nullable(),
+    name: z.string(),
+    /** https only, except loopback (127.0.0.1 / [::1]) for public native clients. */
+    redirectUris: z.array(z.string().url()),
+    createdBy: UserId,
+    createdAt: Timestamp,
+});
+/** Returned ONCE when a client is minted (`loops create`); the registry keeps only a hash of the secret. */
+export const MintedClient = OAuthClientRecord.extend({ clientSecret: z.string().min(32) });
+export const CreateAppInput = z.object({
+    id: AppId,
+    name: z.string().min(1).max(60),
+    redirectUris: z.array(z.string().url()).default([]),
+});
+/** What a Loops access token stands for, resolved by the registry for backend-api `/v1`. */
+export const TokenCaller = z.object({
+    caller: Caller,
+    /** Scopes the token carries: app scopes, or `developer` for the CLI. */
+    scopes: z.array(z.string()),
+    clientId: z.string(),
+    /** Set when the token was issued to an app for one install. */
+    appId: AppId.nullable(),
+    installId: InstallId.nullable(),
+});
+// ── Consent and audit ─────────────────────────────────────────────────────────
+/** One row per consent sheet answered: who approved which scopes for which version. */
+export const ConsentRecord = z.object({
+    id: z.string().regex(/^cns_[A-Za-z0-9]{8,40}$/),
+    installId: InstallId,
+    appId: AppId,
+    versionId: VersionId,
+    workspaceId: WorkspaceId,
+    grantedBy: UserId,
+    scopes: z.array(ScopeSchema),
+    consentedAt: Timestamp,
+});
+export const AuditEntry = z.object({
+    id: z.number().int(),
+    at: Timestamp,
+    actor: z.string(),
+    workspaceId: WorkspaceId.nullable(),
+    appId: AppId.nullable(),
+    versionId: VersionId.nullable(),
+    installId: InstallId.nullable(),
+    /** e.g. `install.created`, `consent.granted`, `developer.granted`, `oauth.client_created`. */
+    action: z.string(),
+    detail: z.record(z.string(), z.unknown()),
+});
+export const AuditQuery = z.object({
+    appId: AppId.optional(),
+    installId: InstallId.optional(),
+    cursor: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+});
+// ── The developer switch ────────────────────────────────────────────────────
+export const WorkspaceDeveloper = z.object({
+    workspaceId: WorkspaceId,
+    userId: UserId,
+    grantedBy: UserId,
+    grantedAt: Timestamp,
+});
+// ── The apps vault (backend-apps-engine, D1 apps-loops-vault) ────────────────
+/** `access_token`, `refresh_token`, `api_key`, `webhook_secret`… */
+export const SecretName = z.string().regex(/^[a-z][a-z0-9_]{0,62}$/, 'Secret name: lowercase letters, digits and underscores');
+/** Where a secret belongs. All four parts are the encryption's additional data, so a copied row will not decrypt. */
+export const SecretRef = z.object({
+    installId: InstallId,
+    workspaceId: WorkspaceId,
+    appId: AppId,
+    name: SecretName,
+});
+/**
+ * The developer's OAuth client secret for their own service is stored once per app under this reserved install id,
+ * in the app owner's workspace: `{ installId: APP_CLIENT_INSTALL_ID, workspaceId: app.ownerWorkspaceId, appId, name: 'oauth_client_secret' }`.
+ * Uninstall never deletes it; only deleting the app does. Added in 0.3.1.
+ */
+export const APP_CLIENT_INSTALL_ID = 'ins_appclient';
+export const APP_CLIENT_SECRET_NAME = 'oauth_client_secret';
+export function appClientSecretRef(appId, ownerWorkspaceId) {
+    return { installId: APP_CLIENT_INSTALL_ID, workspaceId: ownerWorkspaceId, appId, name: APP_CLIENT_SECRET_NAME };
+}
+/** Engine-side code exchange for an app connecting OUT (the handoff at api.thesoogroup.com/oauth/callback). Added in 0.3.1. */
+export const OAuthCodeExchange = z.object({
+    install: SecretRef.omit({ name: true }),
+    ownerWorkspaceId: WorkspaceId,
+    tokenUrl: z.string().url(),
+    clientId: z.string().min(1),
+    code: z.string().min(1),
+    codeVerifier: z.string().min(43).max(128).optional(),
+    redirectUri: z.string().url(),
+});
+/** What anyone outside the engine may see about a secret: never the value. */
+export const SecretInfo = z.object({
+    name: SecretName,
+    keyVersion: z.string(),
+    expiresAt: Timestamp.nullable(),
+    updatedAt: Timestamp,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withloops.ai/contracts",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "The Loops developer platform contracts (zod): app manifest v1, scopes, events, the /v1 API envelope and registry records. Everything else builds on these.",
   "type": "module",
   "license": "UNLICENSED",

package/src/index.ts

@@ -4,3 +4,4 @@ export * from './events.ts';
 export * from './manifest.ts';
 export * from './api.ts';
 export * from './registry.ts';
+export * from './trust.ts';

package/src/manifest.ts

@@ -36,6 +36,8 @@ export const SyncAuth = z.discriminatedUnion('type', [
     type: z.literal('oauth2'),
     authorizeUrl: HttpsUrl,
     tokenUrl: HttpsUrl,
+    /** The developer's OAuth client id at their own service (public). The secret never goes in the manifest: it lives in the vault (APP_CLIENT_SECRET_REF). Added in 0.3.1. */
+    clientId: z.string().min(1).max(256).optional(),
     scopes: z.array(z.string().min(1)).default([]),
     refresh: z.boolean().default(true),
   }),

package/src/trust.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { AppId, InstallId, Timestamp, UserId, VersionId, WorkspaceId } from './ids.ts';
+import { ScopeSchema } from './scopes.ts';
+import { AppRecord, Caller } from './registry.ts';
+
+/**
+ * Layer 1 (Trust): Loops as an OAuth provider, consent, the audit log, the developer switch and the apps vault.
+ * Skill devops-loops-developer-platform §1 (developer access), §6 (vault), §7 (OAuth both ways). Only ever ADD.
+ */
+
+// ── Loops as an OAuth provider (@cloudflare/workers-oauth-provider 1.x in backend-apps-registry) ──
+
+/** The issuer. Discovery at `${LOOPS_OAUTH_ISSUER}/.well-known/oauth-authorization-server`. */
+export const LOOPS_OAUTH_ISSUER = 'https://api.withloops.ai';
+
+export const OAUTH_PATHS = {
+  authorize: '/oauth/authorize',
+  token: '/oauth/token',
+  register: '/oauth/register',
+} as const;
+
+/** The `loops` CLI: a public client (PKCE, loopback redirect on 127.0.0.1, no secret). */
+export const LOOPS_CLI_CLIENT_ID = 'loops-cli';
+
+/** The scope the CLI asks for: build, submit and dev-install apps as the signed-in developer. */
+export const DEVELOPER_SCOPE = 'developer' as const;
+
+export const OAuthClientRecord = z.object({
+  clientId: z.string().min(8).max(128),
+  /** The app this client belongs to; null for first-party clients (the CLI). */
+  appId: AppId.nullable(),
+  name: z.string(),
+  /** https only, except loopback (127.0.0.1 / [::1]) for public native clients. */
+  redirectUris: z.array(z.string().url()),
+  createdBy: UserId,
+  createdAt: Timestamp,
+});
+export type OAuthClientRecord = z.infer<typeof OAuthClientRecord>;
+
+/** Returned ONCE when a client is minted (`loops create`); the registry keeps only a hash of the secret. */
+export const MintedClient = OAuthClientRecord.extend({ clientSecret: z.string().min(32) });
+export type MintedClient = z.infer<typeof MintedClient>;
+
+export const CreateAppInput = z.object({
+  id: AppId,
+  name: z.string().min(1).max(60),
+  redirectUris: z.array(z.string().url()).default([]),
+});
+export type CreateAppInput = z.infer<typeof CreateAppInput>;
+
+/** What a Loops access token stands for, resolved by the registry for backend-api `/v1`. */
+export const TokenCaller = z.object({
+  caller: Caller,
+  /** Scopes the token carries: app scopes, or `developer` for the CLI. */
+  scopes: z.array(z.string()),
+  clientId: z.string(),
+  /** Set when the token was issued to an app for one install. */
+  appId: AppId.nullable(),
+  installId: InstallId.nullable(),
+});
+export type TokenCaller = z.infer<typeof TokenCaller>;
+
+// ── Consent and audit ─────────────────────────────────────────────────────────
+
+/** One row per consent sheet answered: who approved which scopes for which version. */
+export const ConsentRecord = z.object({
+  id: z.string().regex(/^cns_[A-Za-z0-9]{8,40}$/),
+  installId: InstallId,
+  appId: AppId,
+  versionId: VersionId,
+  workspaceId: WorkspaceId,
+  grantedBy: UserId,
+  scopes: z.array(ScopeSchema),
+  consentedAt: Timestamp,
+});
+export type ConsentRecord = z.infer<typeof ConsentRecord>;
+
+export const AuditEntry = z.object({
+  id: z.number().int(),
+  at: Timestamp,
+  actor: z.string(),
+  workspaceId: WorkspaceId.nullable(),
+  appId: AppId.nullable(),
+  versionId: VersionId.nullable(),
+  installId: InstallId.nullable(),
+  /** e.g. `install.created`, `consent.granted`, `developer.granted`, `oauth.client_created`. */
+  action: z.string(),
+  detail: z.record(z.string(), z.unknown()),
+});
+export type AuditEntry = z.infer<typeof AuditEntry>;
+
+export const AuditQuery = z.object({
+  appId: AppId.optional(),
+  installId: InstallId.optional(),
+  cursor: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(25),
+});
+export type AuditQuery = z.infer<typeof AuditQuery>;
+
+// ── The developer switch ────────────────────────────────────────────────────
+
+export const WorkspaceDeveloper = z.object({
+  workspaceId: WorkspaceId,
+  userId: UserId,
+  grantedBy: UserId,
+  grantedAt: Timestamp,
+});
+export type WorkspaceDeveloper = z.infer<typeof WorkspaceDeveloper>;
+
+// ── The apps vault (backend-apps-engine, D1 apps-loops-vault) ────────────────
+
+/** `access_token`, `refresh_token`, `api_key`, `webhook_secret`… */
+export const SecretName = z.string().regex(/^[a-z][a-z0-9_]{0,62}$/, 'Secret name: lowercase letters, digits and underscores');
+export type SecretName = z.infer<typeof SecretName>;
+
+/** Where a secret belongs. All four parts are the encryption's additional data, so a copied row will not decrypt. */
+export const SecretRef = z.object({
+  installId: InstallId,
+  workspaceId: WorkspaceId,
+  appId: AppId,
+  name: SecretName,
+});
+export type SecretRef = z.infer<typeof SecretRef>;
+
+/**
+ * The developer's OAuth client secret for their own service is stored once per app under this reserved install id,
+ * in the app owner's workspace: `{ installId: APP_CLIENT_INSTALL_ID, workspaceId: app.ownerWorkspaceId, appId, name: 'oauth_client_secret' }`.
+ * Uninstall never deletes it; only deleting the app does. Added in 0.3.1.
+ */
+export const APP_CLIENT_INSTALL_ID = 'ins_appclient' as const;
+export const APP_CLIENT_SECRET_NAME = 'oauth_client_secret' as const;
+export function appClientSecretRef(appId: string, ownerWorkspaceId: string): SecretRef {
+  return { installId: APP_CLIENT_INSTALL_ID, workspaceId: ownerWorkspaceId, appId, name: APP_CLIENT_SECRET_NAME };
+}
+
+/** Engine-side code exchange for an app connecting OUT (the handoff at api.thesoogroup.com/oauth/callback). Added in 0.3.1. */
+export const OAuthCodeExchange = z.object({
+  install: SecretRef.omit({ name: true }),
+  ownerWorkspaceId: WorkspaceId,
+  tokenUrl: z.string().url(),
+  clientId: z.string().min(1),
+  code: z.string().min(1),
+  codeVerifier: z.string().min(43).max(128).optional(),
+  redirectUri: z.string().url(),
+});
+export type OAuthCodeExchange = z.infer<typeof OAuthCodeExchange>;
+
+/** What anyone outside the engine may see about a secret: never the value. */
+export const SecretInfo = z.object({
+  name: SecretName,
+  keyVersion: z.string(),
+  expiresAt: Timestamp.nullable(),
+  updatedAt: Timestamp,
+});
+export type SecretInfo = z.infer<typeof SecretInfo>;
+
+// ── RPC surfaces added in L1 (alongside RegistryRpc / EngineRpc) ─────────────
+
+/** `backend-apps-registry` default WorkerEntrypoint implements this as well as `RegistryRpc`. */
+export interface RegistryTrustRpc {
+  /** Create an app owned by the caller's workspace and mint its OAuth client (`loops create`). Developer only. */
+  createApp(caller: Caller, input: CreateAppInput): Promise<{ ok: true; app: AppRecord; client: MintedClient } | { ok: false; error: string }>;
+  /** Resolve a Loops OAuth access token (`Authorization: Bearer …`) for `/v1`; null when unknown, expired or revoked. */
+  resolveToken(bearer: string): Promise<TokenCaller | null>;
+  /** True when the user has the developer switch on in that workspace. */
+  isDeveloper(workspaceId: string, userId: string): Promise<boolean>;
+  /** Owner/Admin only. */
+  setDeveloper(caller: Caller, userId: string, on: boolean): Promise<{ ok: boolean; error?: string }>;
+  listDevelopers(caller: Caller): Promise<WorkspaceDeveloper[]>;
+  /** Consents for one install of the caller's workspace, newest first. */
+  listConsents(caller: Caller, installId: string): Promise<ConsentRecord[]>;
+  /** Audit rows for the caller's workspace (SUPER sees all), newest first. */
+  listAudit(caller: Caller, query: AuditQuery): Promise<{ items: AuditEntry[]; nextCursor: string | null }>;
+}
+
+/** `backend-apps-engine` default WorkerEntrypoint implements this as well as `EngineRpc`. Values go in, never out. */
+export interface EngineVaultRpc {
+  putSecret(ref: SecretRef, value: string, expiresAt?: string | null): Promise<{ ok: true }>;
+  listSecrets(installId: string): Promise<SecretInfo[]>;
+  /** Uninstall calls this; returns how many rows went. */
+  deleteSecrets(installId: string): Promise<{ deleted: number }>;
+  /** Reads the app's client secret, POSTs to tokenUrl, stores access/refresh tokens for the install itself. Values never come back. Added in 0.3.1. */
+  exchangeOAuthCode(input: OAuthCodeExchange): Promise<{ ok: true; expiresAt: string | null } | { ok: false; error: string }>;
+}