@pyric/cli 0.1.0-alpha.30.1 → 0.1.0-alpha.31

package/src/bridge/surface/rules-engines/storage-request-resource.ts

@@ -0,0 +1,275 @@
+/**
+ * The `request.resource` a Storage simulate case builds, by verb, as the live
+ * planes build it.
+ *
+ * - `create` (and the `write` umbrella) is an upload. An upload replaces the
+ *   object, so its `request.resource` carries only what the case sends, with
+ *   an upload's defaults for the rest. A stored object at the path is
+ *   `resource`, never a source of `request.resource` fields.
+ * - `update` is a metadata update: the stored object patched with the case's
+ *   fields. Production builds it whether or not the call changes anything, so
+ *   it is present when the case passes no `data`. With no stored object there
+ *   is nothing to update, and the live request carries none.
+ * - `get`, `list`, `delete` and the `read` umbrella carry none, so a case that
+ *   passes `data` with one is refused rather than evaluated against a binding
+ *   the live request would not have.
+ *
+ * Every field of `data` is checked against `StorageRequestResource`. An
+ * unknown or wrong-typed field is refused by name, because a default in its
+ * place would answer a different question than the one asked.
+ */
+import { requestResourceFor, type StoredMetadata } from 'pyric/storage/internal';
+import type { StorageReference, StorageRequest } from 'pyric/storage';
+
+type RequestResource = NonNullable<StorageRequest['resource']>;
+
+/** What a case's verb and data build: a binding, or why the case is refused. */
+export type RequestResourceOutcome =
+  | { ok: true; resource: RequestResource | undefined }
+  | { ok: false; reason: string };
+
+/** The fields a case's `data` can carry, in the order a refusal lists them. */
+const FIELDS = [
+  'name',
+  'bucket',
+  'size',
+  'contentType',
+  'contentDisposition',
+  'contentEncoding',
+  'contentLanguage',
+  'cacheControl',
+  'metadata',
+  'customMetadata',
+  'generation',
+  'metageneration',
+  'etag',
+] as const;
+
+type Field = (typeof FIELDS)[number];
+
+/** The content fields a case may set to `null`, which the binding then reads as `null`. */
+const NULLABLE_CONTENT = ['contentDisposition', 'contentEncoding', 'contentLanguage', 'cacheControl'] as const;
+
+/** A case's `data`, checked and typed. `null` means the binding reads the field as `null`. */
+interface CaseFields {
+  name?: string;
+  bucket?: string;
+  size?: number;
+  contentType?: string;
+  contentDisposition?: string | null;
+  contentEncoding?: string | null;
+  contentLanguage?: string | null;
+  cacheControl?: string | null;
+  metadata?: Record<string, string> | null;
+  generation?: number | null;
+  metageneration?: number | null;
+  etag?: null;
+}
+
+type Checked<T> = { ok: true; value: T } | { ok: false; reason: string };
+
+const NUMERIC = /^\d+$/;
+
+function refuse<T>(reason: string): Checked<T> {
+  return { ok: false, reason };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function typeName(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `a ${typeof value}`;
+}
+
+/**
+ * A count field: a whole number, or a numeric string as the Rules Test API
+ * tolerates. No object has a negative or fractional size or version.
+ */
+function countOf(field: string, value: unknown): Checked<number> {
+  if (typeof value === 'string' && NUMERIC.test(value)) return { ok: true, value: Number(value) };
+  if (typeof value !== 'number') {
+    return refuse(`data.${field} must be a number or a numeric string, and it is ${typeName(value)}.`);
+  }
+  const whole = Number.isSafeInteger(value) && value >= 0;
+  if (!whole) return refuse(`data.${field} must be a whole number of 0 or more, and it is ${value}.`);
+  return { ok: true, value };
+}
+
+function stringOf(field: string, value: unknown): Checked<string> {
+  if (typeof value === 'string') return { ok: true, value };
+  return refuse(`data.${field} must be a string, and it is ${typeName(value)}.`);
+}
+
+/** Custom metadata: a map of strings, or `null` for none. */
+function metadataOf(field: string, value: unknown): Checked<Record<string, string> | null> {
+  if (value === null) return { ok: true, value: null };
+  if (!isRecord(value)) return refuse(`data.${field} must be a map of strings, and it is ${typeName(value)}.`);
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry !== 'string') {
+      return refuse(`data.${field}.${key} must be a string, and it is ${typeName(entry)}.`);
+    }
+  }
+  return { ok: true, value: value as Record<string, string> };
+}
+
+function isField(key: string): key is Field {
+  return (FIELDS as readonly string[]).includes(key);
+}
+
+/** Check one field and write it onto `out`, or say why it is refused. */
+function checkField(out: CaseFields, field: Field, value: unknown): string | null {
+  const nullable = (NULLABLE_CONTENT as readonly string[]).includes(field);
+  if (nullable && value === null) {
+    out[field as (typeof NULLABLE_CONTENT)[number]] = null;
+    return null;
+  }
+  switch (field) {
+    case 'size': {
+      const checked = countOf(field, value);
+      if (!checked.ok) return checked.reason;
+      out.size = checked.value;
+      return null;
+    }
+    case 'generation':
+    case 'metageneration': {
+      if (value === null) {
+        out[field] = null;
+        return null;
+      }
+      const checked = countOf(field, value);
+      if (!checked.ok) return checked.reason;
+      out[field] = checked.value;
+      return null;
+    }
+    case 'metadata':
+    case 'customMetadata': {
+      if (out.metadata !== undefined) return 'Pass data.metadata or data.customMetadata, not both.';
+      const checked = metadataOf(field, value);
+      if (!checked.ok) return checked.reason;
+      out.metadata = checked.value;
+      return null;
+    }
+    case 'etag':
+      if (value !== null) return `data.etag can only be null, and it is ${typeName(value)}.`;
+      out.etag = null;
+      return null;
+    default: {
+      const checked = stringOf(field, value);
+      if (!checked.ok) return checked.reason;
+      out[field] = checked.value;
+      return null;
+    }
+  }
+}
+
+/** Check a case's `data` against the fields `request.resource` has. */
+function caseFieldsOf(data: unknown): Checked<CaseFields> {
+  if (data === undefined) return { ok: true, value: {} };
+  if (!isRecord(data)) return refuse(`data must be an object, and it is ${typeName(data)}.`);
+  const out: CaseFields = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!isField(key)) {
+      return refuse(`data.${key} is not a field of request.resource. Its fields are ${FIELDS.join(', ')}.`);
+    }
+    const reason = checkField(out, key, value);
+    if (reason !== null) return refuse(reason);
+  }
+  return { ok: true, value: out };
+}
+
+/** Whether a verb writes, and which write builds its binding. */
+function writeOf(operation: string): 'upload' | 'metadataUpdate' | null {
+  if (operation === 'create' || operation === 'write') return 'upload';
+  if (operation === 'update') return 'metadataUpdate';
+  return null;
+}
+
+function presentOrUndefined<T>(value: T | null | undefined): T | undefined {
+  return value === null ? undefined : value;
+}
+
+/**
+ * The binding an upload builds from the case alone, with an upload's defaults.
+ * An empty `contentType` takes the default too, as a live upload's does.
+ */
+function uploadResource(object: StorageReference, fields: CaseFields): RequestResource {
+  return requestResourceFor(
+    {
+      fullPath: fields.name ?? object.fullPath,
+      bucket: fields.bucket ?? object.bucket,
+      size: fields.size ?? 0,
+      contentType: fields.contentType || 'application/octet-stream',
+      customMetadata: presentOrUndefined(fields.metadata),
+      cacheControl: presentOrUndefined(fields.cacheControl),
+      contentDisposition: presentOrUndefined(fields.contentDisposition),
+      contentEncoding: presentOrUndefined(fields.contentEncoding),
+      contentLanguage: presentOrUndefined(fields.contentLanguage),
+    },
+    'upload',
+  );
+}
+
+/** A field the case names wins; one it leaves out keeps the stored value. */
+function patched<T>(set: T | null | undefined, stored: T | undefined): T | undefined {
+  if (set === null) return undefined;
+  return set ?? stored;
+}
+
+/** The binding a metadata update builds: the stored object patched with the case. */
+function updateResource(fields: CaseFields, existing: StoredMetadata): RequestResource {
+  return requestResourceFor(
+    {
+      fullPath: fields.name ?? existing.fullPath,
+      bucket: fields.bucket ?? existing.bucket,
+      size: fields.size ?? existing.size,
+      contentType: fields.contentType ?? existing.contentType,
+      customMetadata: patched(fields.metadata, existing.customMetadata),
+      cacheControl: patched(fields.cacheControl, existing.cacheControl),
+      contentDisposition: patched(fields.contentDisposition, existing.contentDisposition),
+      contentEncoding: patched(fields.contentEncoding, existing.contentEncoding),
+      contentLanguage: patched(fields.contentLanguage, existing.contentLanguage),
+      generation: existing.generation,
+      metageneration: existing.metageneration,
+    },
+    'metadataUpdate',
+  );
+}
+
+/** Fields a case sets to `null` read as `null`, whatever the write's default. */
+function applyNulls(resource: RequestResource, fields: CaseFields): RequestResource {
+  for (const field of NULLABLE_CONTENT) {
+    if (fields[field] === null) resource[field] = null;
+  }
+  if (fields.metadata === null) resource.metadata = null;
+  if (fields.generation !== undefined) resource.generation = fields.generation;
+  if (fields.metageneration !== undefined) resource.metageneration = fields.metageneration;
+  if (fields.etag === null) resource.etag = null;
+  return resource;
+}
+
+/**
+ * The `request.resource` one simulate case builds for its verb, or why the
+ * case is refused.
+ */
+export function simulatedRequestResource(
+  object: StorageReference,
+  operation: string,
+  data: unknown,
+  existing: StoredMetadata | undefined,
+): RequestResourceOutcome {
+  const write = writeOf(operation);
+  if (write === null) {
+    if (data === undefined) return { ok: true, resource: undefined };
+    return { ok: false, reason: `a ${operation} request carries no request.resource; remove 'data'.` };
+  }
+  const fields = caseFieldsOf(data);
+  if (!fields.ok) return fields;
+  if (write === 'upload') return { ok: true, resource: applyNulls(uploadResource(object, fields.value), fields.value) };
+  // An update of an object that is not stored carries none, as the live
+  // metadata update builds none before it reports the object missing.
+  if (existing === undefined) return { ok: true, resource: undefined };
+  return { ok: true, resource: applyNulls(updateResource(fields.value, existing), fields.value) };
+}

package/src/bridge/surface/rules-engines/storage.ts

@@ -5,20 +5,23 @@ import {
   compileStorageRules,
   getStorageCrossServiceIam,
   getStorageService,
+  bindRulesBucket,
   replaceStorageRules,
-  requestResourceFor,
   resourceFromStored,
+  rulesBucketName,
+  targetOf,
   storageFirestoreLookup,
-  type StoredMetadata,
 } from 'pyric/storage/internal';
 import { asSentence } from 'pyric/sandbox/internal';
+import { lint as lintRules, type RuleIssue } from 'pyric/rules';
 import { describeCompileLimitViolations, sourceCompileLimitViolations } from 'pyric/rules/internal';
 import { operationFailure } from '../context.js';
 import { requestInstant } from '../request-instant.js';
 import { storageFor } from '../service-handles.js';
-import { activeStorageRules, rulesRequestPath } from '../storage-rules.js';
-import type { SurfaceContext } from '../types.js';
+import { activeStorageRules } from '../storage-rules.js';
+import type { OperationResult, SurfaceContext } from '../types.js';
 import { markLintFindings } from '../rules-verdict.js';
+import { simulatedRequestResource } from './storage-request-resource.js';
 import type { RulesEngine, RulesSourceProblem } from './types.js';
 
 /** What a call has to do when it named no source and the sandbox holds none. */
@@ -39,72 +42,6 @@ function identityFor(
   return { uid: held.uid, token: held.token ?? {} };
 }
 
-function requestResourceFromData(
-  object: StorageReference,
-  operation: string,
-  data: unknown,
-  existing: StoredMetadata | undefined,
-) {
-  if (data === undefined || typeof data !== 'object' || data === null || Array.isArray(data)) {
-    return undefined;
-  }
-  const raw = data as Record<string, unknown>;
-  const writeKind = operation === 'update' ? 'metadataUpdate' : 'upload';
-  const customMetadata =
-    raw.metadata !== undefined &&
-    typeof raw.metadata === 'object' &&
-    raw.metadata !== null &&
-    !Array.isArray(raw.metadata)
-      ? (raw.metadata as Record<string, string>)
-      : raw.customMetadata !== undefined &&
-          typeof raw.customMetadata === 'object' &&
-          raw.customMetadata !== null &&
-          !Array.isArray(raw.customMetadata)
-        ? (raw.customMetadata as Record<string, string>)
-        : existing?.customMetadata;
-  const base = requestResourceFor(
-    {
-      fullPath: typeof raw.name === 'string' ? raw.name : object.fullPath,
-      bucket: typeof raw.bucket === 'string' ? raw.bucket : object.bucket,
-      size: typeof raw.size === 'number' ? raw.size : (existing?.size ?? 0),
-      contentType:
-        typeof raw.contentType === 'string'
-          ? raw.contentType
-          : (existing?.contentType ?? 'application/octet-stream'),
-      customMetadata,
-      cacheControl: typeof raw.cacheControl === 'string' ? raw.cacheControl : existing?.cacheControl,
-      contentDisposition:
-        typeof raw.contentDisposition === 'string'
-          ? raw.contentDisposition
-          : existing?.contentDisposition,
-      contentEncoding:
-        typeof raw.contentEncoding === 'string' ? raw.contentEncoding : existing?.contentEncoding,
-      contentLanguage:
-        typeof raw.contentLanguage === 'string' ? raw.contentLanguage : existing?.contentLanguage,
-      generation:
-        typeof raw.generation === 'number' || typeof raw.generation === 'string'
-          ? String(raw.generation)
-          : existing?.generation,
-      metageneration:
-        typeof raw.metageneration === 'number' || typeof raw.metageneration === 'string'
-          ? String(raw.metageneration)
-          : existing?.metageneration,
-    },
-    writeKind,
-  );
-  if (raw.metadata === null || raw.customMetadata === null) base.metadata = null;
-  if (raw.contentDisposition === null) base.contentDisposition = null;
-  if (raw.contentEncoding === null) base.contentEncoding = null;
-  if (raw.contentLanguage === null) base.contentLanguage = null;
-  if (raw.cacheControl === null) base.cacheControl = null;
-  if (typeof raw.generation === 'number' || raw.generation === null) base.generation = raw.generation;
-  if (typeof raw.metageneration === 'number' || raw.metageneration === null) {
-    base.metageneration = raw.metageneration;
-  }
-  if (raw.etag === null) base.etag = null;
-  return base;
-}
-
 /**
  * Why `compileStorageRules` refused a source: production's compile rejections
  * when the source parses and breaks a compile limit, otherwise the failure it
@@ -125,6 +62,33 @@ function sourceProblem(source: string, error: unknown): RulesSourceProblem {
   };
 }
 
+/** One finding as a line: its code, where it is, and what it says. */
+function findingLine(issue: RuleIssue): string {
+  const where = issue.path === undefined ? '' : ` at ${issue.path}`;
+  return `${issue.code}${where}: ${issue.message}`;
+}
+
+/**
+ * A compiled source's lint result. An error-severity finding fails the lint,
+ * as a security hole or a construct production reads differently is a reason
+ * not to deploy; warnings alone pass, and are listed.
+ */
+function lintResult(issues: RuleIssue[]): OperationResult {
+  const errors = issues.filter((issue) => issue.severity === 'error');
+  const warnings = issues.filter((issue) => issue.severity !== 'error');
+  const warningNote =
+    warnings.length === 0 ? '' : ` Warnings: ${warnings.map((issue) => issue.code).join(', ')}.`;
+  const data = { errors: errors.map(findingLine), issues };
+  if (errors.length > 0) {
+    return markLintFindings({
+      ok: false,
+      summary: `Storage rules lint found ${errors.length} error(s). ${errors.map(findingLine).join(' ')}${warningNote}`,
+      data,
+    });
+  }
+  return { ok: true, summary: `Storage rules compiled with no lint errors.${warningNote}`, data };
+}
+
 export const STORAGE_RULES: RulesEngine = {
   requestMethods: ['get', 'list', 'create', 'update', 'delete', 'read', 'write'],
 
@@ -142,6 +106,9 @@ export const STORAGE_RULES: RulesEngine = {
     if (source === null) {
       return operationFailure(NO_RULES_LOADED);
     }
+    // The shared linter is what `lint()` from `pyric/rules` runs, so both
+    // report the same findings for one source.
+    const issues = lintRules(source);
     try {
       compileStorageRules(source);
     } catch (error) {
@@ -149,10 +116,10 @@ export const STORAGE_RULES: RulesEngine = {
       return markLintFindings({
         ok: false,
         summary: `${message} ${sourceProblem(source, error).fix}`,
-        data: { errors: [message] },
+        data: { errors: [message], issues },
       });
     }
-    return { ok: true, summary: 'Storage rules parsed with no errors.', data: { errors: [] } };
+    return lintResult(issues);
   },
 
   async simulate(ctx, request) {
@@ -173,23 +140,29 @@ export const STORAGE_RULES: RulesEngine = {
     const existing = object.fullPath
       ? await service.backend.getMetadata(object.fullPath, object.bucket)
       : undefined;
-    const requestResource = requestResourceFromData(
-      object,
-      request.operation,
-      request.data,
-      existing,
-    );
-    const evaluated = evaluateStorageRules(
-      parsed,
+    const built = simulatedRequestResource(object, request.operation, request.data, existing);
+    if (!built.ok) {
+      return operationFailure(`${request.operation} ${request.path}: ${built.reason}`);
+    }
+    const requestResource = built.resource;
+    // Rules see the bucket under the name the app knows it by, as the live
+    // planes bind it (ST-H2-4).
+    const input = bindRulesBucket(
       {
         request: {
           auth: identityFor(ctx, request.uid),
           method: request.operation as StorageRequestMethod,
-          path: rulesRequestPath(object),
+          path: object.fullPath,
           ...(requestResource !== undefined ? { resource: requestResource } : {}),
         },
         resource: resourceFromStored(existing),
       },
+      object.bucket,
+      rulesBucketName(object.bucket, targetOf(object.storage).bucketName),
+    );
+    const evaluated = evaluateStorageRules(
+      parsed,
+      input,
       new Date(requestInstant(ctx, request.requestTime)),
       // A rule reaching into Firestore is answered here the way the
       // enforcement path answers it, under the posture the sandbox is in, so a

package/src/bridge/surface/sandbox-context.ts

@@ -0,0 +1,49 @@
+/**
+ * The execution context a method record gets wherever the sandbox lives.
+ *
+ * Its dispatcher reaches only the forwarded tool families, through the same
+ * `buildSandboxDispatcher` the page and the SharedWorker already run, and it
+ * reads no file. A host that keeps its sandbox in a browser can therefore
+ * build one and run any record marked `runsIn: 'sandbox'` against it. The
+ * bridge process builds the wider context in `./context.ts` on top of this one.
+ */
+import type { LocalSandbox } from 'pyric/sandbox';
+import { buildSandboxDispatcher } from '../client/dispatch.js';
+import { accountLookupFor } from './app-session.js';
+import type { DatabaseInstanceCatalog } from './database-instance-catalog.js';
+import { SurfaceIdentity } from './identity.js';
+import type { OperationResult, SandboxSurfaceContext } from './types.js';
+
+/**
+ * Build the context for one sandbox. `databaseInstances` answers which RTDB
+ * instances a `database` method may name, from what the host serves.
+ */
+export function createSandboxSurfaceContext(
+  sandbox: LocalSandbox,
+  databaseInstances: () => Promise<DatabaseInstanceCatalog>,
+): SandboxSurfaceContext {
+  return {
+    sandbox,
+    dispatch: buildSandboxDispatcher(sandbox),
+    identity: new SurfaceIdentity(accountLookupFor(sandbox)),
+    databaseInstances,
+  };
+}
+
+/**
+ * Call one existing sandbox tool under the held identity. Arguments are
+ * objects in and objects out; nothing is JSON-encoded on the way through.
+ */
+export async function callSandboxTool(
+  ctx: SandboxSurfaceContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<OperationResult> {
+  return ctx.dispatch(name, args, ctx.identity.lens());
+}
+
+/** Report a failure in the shape every handler returns. */
+export function operationFailure(summary: string, data?: unknown): OperationResult {
+  if (data === undefined) return { ok: false, summary };
+  return { ok: false, summary, data };
+}

package/src/bridge/surface/service-handles.ts

@@ -12,15 +12,15 @@ import { getAdminDatabase, getDatabase, type Database } from 'pyric/database';
 import { getAdminFirestore, getFirestore, type Firestore } from 'pyric/firestore';
 import { getMessagingBroker, type MessagingBroker } from 'pyric/messaging/internal';
 import { getStorageSandbox, type FirebaseStorage } from 'pyric/storage';
-import { getAdminStorageSandbox } from 'pyric/storage/internal';
-import type { SurfaceContext } from './types.js';
+import { getAdminStorageSandbox, nameStorageBucket } from 'pyric/storage/internal';
+import type { SandboxSurfaceContext } from './types.js';
 
 /**
  * A Realtime Database handle for the held identity, on the instance `selector`
  * names (`instanceSelector` in `database-instance.ts`); absent is the default
  * instance. Each instance enforces its own rules.
  */
-export function databaseFor(ctx: SurfaceContext, selector?: string): Database {
+export function databaseFor(ctx: SandboxSurfaceContext, selector?: string): Database {
   if (ctx.identity.bypassesRules()) return getAdminDatabase(ctx.sandbox, selector);
   return getDatabase(ctx.sandbox.withAuth(ctx.identity.authState()), selector);
 }
@@ -32,15 +32,19 @@ export function databaseFor(ctx: SurfaceContext, selector?: string): Database {
 // `Firestore` handle rather than the dispatcher's plain-object tool call.
 
 /** A Cloud Firestore handle for the held identity, for the methods that build a `Query` directly. */
-export function firestoreFor(ctx: SurfaceContext): Firestore {
+export function firestoreFor(ctx: SandboxSurfaceContext): Firestore {
   if (ctx.identity.bypassesRules()) return getAdminFirestore(ctx.sandbox);
   return getFirestore(ctx.sandbox.withAuth(ctx.identity.authState()));
 }
 
 /** A Cloud Storage handle for the held identity. */
-export function storageFor(ctx: SurfaceContext): FirebaseStorage {
-  if (ctx.identity.bypassesRules()) return getAdminStorageSandbox(ctx.sandbox);
-  return getStorageSandbox(ctx.sandbox.withAuth(ctx.identity.authState()));
+export function storageFor(ctx: SandboxSurfaceContext): FirebaseStorage {
+  // Rules, and a simulation on this handle, see the default bucket under the
+  // served app's name for it, as the app's own requests do (ST-H2-4).
+  const handle = ctx.identity.bypassesRules()
+    ? getAdminStorageSandbox(ctx.sandbox)
+    : getStorageSandbox(ctx.sandbox.withAuth(ctx.identity.authState()));
+  return nameStorageBucket(handle, ctx.storageBucketName?.());
 }
 
 /**
@@ -50,7 +54,7 @@ export function storageFor(ctx: SurfaceContext): FirebaseStorage {
  * routed through the held identity the way firestore, database, and storage
  * are.
  */
-export function messagingBrokerFor(ctx: SurfaceContext): MessagingBroker {
+export function messagingBrokerFor(ctx: SandboxSurfaceContext): MessagingBroker {
   return getMessagingBroker(ctx.sandbox);
 }
 
@@ -59,7 +63,7 @@ export function messagingBrokerFor(ctx: SurfaceContext): MessagingBroker {
  * the way messaging does not, so this is not routed through the held
  * identity either.
  */
-export function aiFor(ctx: SurfaceContext): AI {
+export function aiFor(ctx: SandboxSurfaceContext): AI {
   return getAI(ctx.sandbox);
 }
 

package/src/bridge/surface/sign-in.ts

@@ -19,9 +19,9 @@ import { getAuth, sandbox as authSandbox } from 'pyric/auth';
 import type { LocalSandbox } from 'pyric/sandbox';
 
 import { describeAppSession, readAppSession } from './app-session.js';
-import { operationFailure } from './context.js';
+import { operationFailure } from './sandbox-context.js';
 import { describeAgentIdentity } from './held-identity.js';
-import type { OperationResult, SurfaceContext } from './types.js';
+import type { OperationResult, SandboxSurfaceContext } from './types.js';
 
 /** The fix for a credential no account in the pool matches. */
 export const MISSING_ACCOUNT_FIX =
@@ -66,7 +66,7 @@ export function scopeToStoredTenant(sandbox: LocalSandbox, subject: SignInSubjec
  * Report what a sign-in or a sign-out did: the app session it moved, and the
  * agent identity it left alone.
  */
-export function reportAppSession(ctx: SurfaceContext): OperationResult {
+export function reportAppSession(ctx: SandboxSurfaceContext): OperationResult {
   const appSession = readAppSession(ctx.sandbox);
   const agent = ctx.identity.describe();
   return {

package/src/bridge/surface/storage-rules.ts

@@ -9,10 +9,9 @@
  * ruleset.
  */
 import type { LocalSandbox } from 'pyric/sandbox';
-import type { StorageReference } from 'pyric/storage';
 import { getStorageRulesResolution } from 'pyric/storage/internal';
 import { storageFor } from './service-handles.js';
-import type { SurfaceContext } from './types.js';
+import type { SandboxSurfaceContext } from './types.js';
 
 /**
  * A project's storage rules source that could not be loaded into the service
@@ -30,19 +29,8 @@ export function rememberUnloadedStorageRules(sandbox: LocalSandbox, source: stri
  * The storage rules source in force, or the project source that failed to
  * load, or null when the service was opened without rules.
  */
-export function activeStorageRules(ctx: SurfaceContext): string | null {
+export function activeStorageRules(ctx: SandboxSurfaceContext): string | null {
   const loaded = getStorageRulesResolution(storageFor(ctx))?.source;
   if (loaded !== undefined) return loaded;
   return unloadedStorageRules.get(ctx.sandbox) ?? null;
 }
-
-/**
- * The path a Storage rule matches on. Rules address an object through the
- * bucket, as `b/<bucket>/o/<object path>`, while the operation set names the
- * object path alone.
- */
-export function rulesRequestPath(object: StorageReference): string {
-  return object.fullPath === ''
-    ? `b/${object.bucket}/o`
-    : `b/${object.bucket}/o/${object.fullPath}`;
-}

package/src/bridge/surface/stored-identity.ts

@@ -18,7 +18,7 @@
 import { getAuth, sandbox as authSandbox } from 'pyric/auth';
 
 import type { IdentityInput } from './identity.js';
-import type { SurfaceContext } from './types.js';
+import type { SandboxSurfaceContext } from './types.js';
 
 /** The tenant and claims one user record holds, as a caller may override them. */
 export interface NamedIdentity {
@@ -31,7 +31,7 @@ export interface NamedIdentity {
  * session has no remembered projection, and without this lookup it would act
  * untenanted and unclaimed, and the verdict would explain the wrong denial.
  */
-export function storedIdentity(ctx: SurfaceContext, uid: string): NamedIdentity {
+export function storedIdentity(ctx: SandboxSurfaceContext, uid: string): NamedIdentity {
   const stored = authSandbox.exportUsers(getAuth(ctx.sandbox)).find((user) => user.uid === uid);
   const identity: NamedIdentity = {};
   if (stored?.tenantId !== undefined) identity.tenant = stored.tenantId;
@@ -44,7 +44,7 @@ export function storedIdentity(ctx: SurfaceContext, uid: string): NamedIdentity
  * the call named written over it field by field.
  */
 export function impersonatedIdentity(
-  ctx: SurfaceContext,
+  ctx: SandboxSurfaceContext,
   uid: string,
   named: NamedIdentity,
 ): IdentityInput {