@intentic/sandbox-contract 1.239.0 → 1.242.0

package/src/credential-material.ts

@@ -53,13 +53,23 @@ const MIN_VALUE = 6;
  * content of `.git-credentials`, and the shape a `DATABASE_URL` hides one in).
  *
  * These are checked first and independently of any key, because half of these files have no `key = value` in
- * them at all. */
-const TOKEN_SHAPES = [
+ * them at all.
+ *
+ * SPLIT IN TWO because the two halves are MASKED differently (maskCredentialMaterial below) though they DETECT
+ * identically: a structural shape matches a header or an authority whose surroundings must survive the mask (a
+ * PEM's body is the secret, not its `-----BEGIN` line; a URL's host is not the secret), and an issued token is
+ * the credential entire, wherever it turns up, with nothing around it to keep. */
+const STRUCTURAL_SHAPES = [
     /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/,
     /PuTTY-User-Key-File-\d/,
-    // scheme://user:password@host — the password is the point; a Sentry DSN (`https://key@host`) has no colon
-    // before the `@` and is deliberately not this.
-    /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@/i,
+    /* scheme://user:password@host — the password is the point; a Sentry DSN (`https://key@host`) has no colon
+     * before the `@` and is deliberately not this. A userinfo that is nothing but asterisks is a password
+     * somebody already masked (maskCredentialMaterial below leaves this exact shape behind), and reading it as
+     * a credential would have a masked file still answer "yes, there is one in here". */
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:(?!\*+@)[^\s/@]{3,}@/i,
+];
+
+const ISSUED_TOKENS = [
     /\bnpm_[A-Za-z0-9]{30,}/,
     /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/,
     /\bgithub_pat_[A-Za-z0-9_]{50,}/,
@@ -76,6 +86,8 @@ const TOKEN_SHAPES = [
     /\bey[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9_-]{10,}\./,
 ];
 
+const TOKEN_SHAPES = [...STRUCTURAL_SHAPES, ...ISSUED_TOKENS];
+
 /* A VALUE DEFERRED TO SOMEWHERE ELSE, removed before anything is read, because it is not one value but two
  * things to get wrong. `STRIPE_SECRET={{secret:STRIPE}}` holds no credential — that is the platform's own
  * convention for a file that must not hold one — and yet it reads as a credential twice over: the outer
@@ -98,3 +110,72 @@ export const holdsCredentialMaterial = (file: string): boolean => {
     }
     return false;
 };
+
+/* THE SAME DEFINITION APPLIED RATHER THAN ASKED: the text back with every credential in it blanked, and
+ * everything else byte for byte.
+ *
+ * WHERE IT RUNS is what lets it be this blunt (sandbox agent/agent-redaction.ts): only over a tool result whose
+ * INPUT named credential material — a Read of `.env`, a `cat ~/.npmrc`, a Grep through `~/.aws`. The name
+ * heuristics that run over ARBITRARY output have to be timid, and the timidity is measured rather than
+ * theoretical: matching on the key alone rewrote `oauthToken === undefined` mid-comparison and broke a JSON
+ * body at `"cacheReadTokens":26170149`. This pass is pointed at a file the path table already calls a
+ * credential store, where a `key = value` IS the credential and there is no prose to protect.
+ *
+ * IT COVERS THE HALF THE VAULT CANNOT. Value masking is exact and complete for what this sandbox STORES, and
+ * blind to everything else: the project's own `.env`, a token a deploy minted an hour ago, whatever the owner
+ * pasted into the repo this agent was pointed at. Those are the credentials a read actually leaks, and with
+ * them blanked a read is worth about as much to a stranger as the file's key names — which is what lets the
+ * command gate stop asking about READS and ask about SENDING (sandbox guard/actions.ts).
+ *
+ * THE MASK IS ANONYMOUS, never a `{{secret:name}}` reference. A reference is a promise that the exits resolve
+ * it back to a value, and this pass is inferring from shape: minting one would put a token in the model's hands
+ * that resolves to nothing, discovered when the deploy 401s. The cost is stated plainly: a file the model
+ * rewrites wholesale from a masked read loses the value it was never shown. That is the same trade the terminal
+ * filter has always made, and the alternative is handing the model the credential so it can copy it back.
+ *
+ * A PuTTY `.ppk` body is the known gap: unlike PEM it has no closing line to bound the mask, so its key
+ * material survives this pass. The file still reads as credential material to everything else here, so the gate
+ * still asks before a command carrying it reaches the internet. */
+const MASK = "***";
+
+// The `g` twins, built once: the tables above are written without `g` because `test` is what the detector
+// wants, and `replace`/`replaceAll` demands one.
+const globally = (patterns: readonly RegExp[]): readonly RegExp[] => patterns.map((pattern) => new RegExp(pattern.source, `${pattern.flags}g`));
+const ISSUED_TOKENS_G = globally(ISSUED_TOKENS);
+const CREDENTIAL_ASSIGNMENT_G = new RegExp(CREDENTIAL_ASSIGNMENT.source, CREDENTIAL_ASSIGNMENT.flags);
+
+/* The two structural shapes that mask to something other than themselves. A PEM's header and footer stay so the
+ * model can still see WHICH key it is looking at and that a key is what it is looking at; a URL keeps its scheme,
+ * user and host, because a `DATABASE_URL` with the host blanked is a connection string nobody can debug. */
+const PRIVATE_KEY_BLOCK = /(-----BEGIN ((?:[A-Z0-9]+ )*)PRIVATE KEY-----)[\s\S]*?(-----END \2PRIVATE KEY-----)/g;
+const URL_PASSWORD = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:)(?!\*+@)[^\s/@]{3,}@/gi;
+
+/* A VALUE THAT OPENS A DEFERRED REFERENCE, skipped whole. The detector cuts these out before it looks
+ * (DEFERRED_VALUE); masking cannot cut anything out, so it recognises the OPENER instead — and the opener is
+ * what a truncated one leaves behind. `STRIPE_SECRET={{secret:STRIPE}}` is the case that matters: the bare-value
+ * arm stops at the first `}`, so what reaches this test is `{{secret:STRIPE`, which no whole-value placeholder
+ * pattern can match and which masking would turn into `***}}` — this workspace's own convention for a file that
+ * holds no credential, silently vandalised. Anchored at the start so a generated password that merely CONTAINS
+ * a `$` is still masked. */
+const DEFERRED_OPENER = /^(?:\{\{|\$)/;
+
+export const maskCredentialMaterial = (text: string): string =>
+    ISSUED_TOKENS_G.reduce((masked, token) => masked.replace(token, MASK), text)
+        .replace(PRIVATE_KEY_BLOCK, `$1\n${MASK}\n$3`)
+        .replace(URL_PASSWORD, `$1${MASK}@`)
+        /* The value of a credential-named assignment, in place, with its key, separator and quoting left
+         * standing: `GITHUB_TOKEN="***"` is a line the model can still reason about and still rewrite, where a
+         * blanked-out line is a config it cannot read at all. The skips are the detector's own — a value too
+         * short to be issued, a template's placeholder, a `${VAR}` or `{{secret:NAME}}` deferred elsewhere —
+         * so the two halves agree on what a credential is and nothing is masked that was never one. */
+        .replace(CREDENTIAL_ASSIGNMENT_G, (match, ...groups: unknown[]) => {
+            const value = (groups[0] ?? groups[1] ?? groups[2] ?? "") as string;
+            const trimmed = value.trim();
+            if (trimmed.length < MIN_VALUE || PLACEHOLDER.test(trimmed) || DEFERRED_OPENER.test(trimmed)) {
+                return match;
+            }
+            // The value is the last thing the pattern matched, so its own text locates it inside the match
+            // without the pattern having to hand back offsets.
+            const at = match.lastIndexOf(value);
+            return `${match.slice(0, at)}${MASK}${match.slice(at + value.length)}`;
+        });

package/src/definition.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DefinitionActionSchema } from "./definition-action.js";
+import { NeedsActionSchema } from "./needs-action.js";
 import { CapabilitySchema } from "./schemas/capabilities.js";
 import { SandboxSettingsSchema } from "./schemas/settings.js";
 
@@ -34,7 +34,7 @@ export type DefinitionRepository = z.infer<typeof DefinitionRepositorySchema>;
 /* THE WORKSPACE ITSELF, by reference. `/work` is a git repo of its own (the daemon's `root` scope, git dir on
  * /history), tracking every workspace file that is not a nested repo, the reference shelf, or daemon-internal
  * state — which by the versioned-state allowlist means the owner's AUTHORED content: notes, skills, personas,
- * automations, workflow and loop designs, drafts, workspace extensions. None of that has a source anywhere else,
+ * automations, workflow and loop designs, approvals, workspace extensions. None of that has a source anywhere else,
  * so before this section a definition could only shrug at it and a bundle was the sole way to move it.
  *
  * With a remote it becomes referenceable like any other repo, which is the whole point: `[workspace]` plus
@@ -105,66 +105,28 @@ export const SandboxDefinitionSchema = z.strictObject({
 });
 export type SandboxDefinition = z.infer<typeof SandboxDefinitionSchema>;
 
-// One "do this by hand" line, the same honesty unit ImportReportSchema carries: a subject the UI bolds and a
-// detail written as an instruction to the owner. Defined in its own leaf module (definition-action.ts says
-// why) and re-exported here, where every consumer of the definition surface finds it.
-export { DefinitionActionSchema, type DefinitionAction } from "./definition-action.js";
+// One "do this by hand" line, the honesty unit the arrival surface carries too: a subject the UI bolds and a
+// detail written as an instruction to the owner. Defined in its own leaf module (needs-action.ts says why)
+// and re-exported here, where every consumer of the definition surface finds it.
+export { NeedsActionSchema, type NeedsAction } from "./needs-action.js";
 
 // What GET /definition answers: the emitted TOML, plus what the derivation could not express (a repo with no
 // remote), listed rather than silent, the export's own `excluded` discipline.
 export const DefinitionExportSchema = z.object({
     toml: z.string(),
-    omitted: z.array(DefinitionActionSchema),
+    omitted: z.array(NeedsActionSchema),
 });
 export type DefinitionExport = z.infer<typeof DefinitionExportSchema>;
 
-// One appliable piece of a held definition, the checklist row the owner ticks. Mirrors MigrationItemSchema's
-// role; the ids are deterministic ("repo:intentic", "capability:github") so the re-derived apply names the
-// same items the owner reviewed.
-export const DefinitionItemSchema = z.object({
-    id: z.string(),
-    kind: z.enum(["workspace", "repo", "capability", "environment", "settings"]),
-    label: z.string(),
-    detail: z.string().optional(),
-    /* False when the target already holds this piece (the repo's directory exists, a capability with that id
-     * exists): a definition lands BESIDE what is there, never over it, so an inapplicable item renders greyed
-     * with its reason rather than disappearing. */
-    applicable: z.boolean(),
-    reason: z.string().optional(),
-});
-export type DefinitionItem = z.infer<typeof DefinitionItemSchema>;
-
-export const DefinitionPlanSchema = z.object({
-    // Names the held definition for the apply call. Minted per plan; a new plan replaces the held one.
-    token: z.string(),
-    name: z.string().optional(),
-    items: z.array(DefinitionItemSchema),
-    // What is already known not to move mechanically (credentials to enter, an overlay to approve), surfaced
-    // at PREVIEW time so the owner ticks with open eyes, the migration surface's rule.
-    needsAction: z.array(DefinitionActionSchema),
-});
-export type DefinitionPlan = z.infer<typeof DefinitionPlanSchema>;
-
-export const DefinitionApplySchema = z.object({
-    token: z.string(),
-    // The ticked item ids. Ids the re-derived plan does not contain are ignored rather than erroring.
-    items: z.array(z.string()),
-});
-export type DefinitionApply = z.infer<typeof DefinitionApplySchema>;
-
-export const DefinitionReportSchema = z.object({
-    applied: z.array(z.object({ id: z.string(), label: z.string() })),
-    // Ticked and did not land, each with the reason (a clone that failed, a full disk). Distinct from
-    // inapplicable items, which were never attempted.
-    failed: z.array(z.object({ id: z.string(), label: z.string(), error: z.string() })),
-    needsAction: z.array(DefinitionActionSchema),
-});
-export type DefinitionReport = z.infer<typeof DefinitionReportSchema>;
+/* APPLYING one is not here. A definition is one of four things that can ARRIVE in a sandbox, and it lands
+ * through the shared pipeline in arrival.ts (ArrivalPlan → ArrivalApply → ArrivalReport) rather than through
+ * a plan/apply/report trio of its own. What stays on this file is the outbound half and the read: deriving
+ * the document, and where this sandbox stands relative to one. */
 
 // Where this sandbox stands relative to a definition: one line per difference, empty when they agree. The
 // drift answer, computable because the emitter is deterministic.
 export const DefinitionDiffSchema = z.object({
-    differences: z.array(DefinitionActionSchema),
+    differences: z.array(NeedsActionSchema),
 });
 export type DefinitionDiff = z.infer<typeof DefinitionDiffSchema>;
 
@@ -213,18 +175,28 @@ export type WorkspaceRemote = z.infer<typeof WorkspaceRemoteSchema>;
  * A bundle is DEFINITION + STATE: its manifest embeds the same definition `GET /definition` emits, and the
  * tar entries behind it carry what no definition can reference (git dirs, transcripts, ledgers). One schema,
  * two doors, which is what keeps the two formats from drifting into different answers about what an
- * environment IS. Version 2 replaced the ad-hoc `environment` facts block with the definition; a v1 bundle is
- * refused by version rather than guessed at, like any other manifest this daemon cannot read.
+ * environment IS. A manifest whose version this daemon does not know is refused rather than guessed at.
+ *
+ * Version 3 added `repos`, and it is the field that made a bundle previewable. Taking one in is now a plan
+ * the owner ticks (arrival.ts), and a plan has to say what is in the tar BEFORE the tar is read: which
+ * repositories a bundle carries could previously only be learned by walking every entry, because
+ * `definition.repositories` lists only the ones that HAVE a remote to be named by. A bundle that cannot
+ * describe its own contents can only be offered whole, which is exactly the all-or-nothing this replaced.
  */
 export const BundleManifestSchema = z.object({
     // Bumped when the layout changes in a way an older daemon would misread. Refused rather than guessed at.
-    version: z.literal(2),
+    version: z.literal(3),
     // Where it came from, for the report's first line. Never used to authorize anything.
     sandbox: z.object({ name: z.string() }).optional(),
     createdAt: z.number(),
     // The owner's export-time choice; the restorer re-derives every decision from the manifests rather than
     // trusting this, and uses it only to explain what is missing.
     secrets: z.boolean(),
+    /* Every repository whose real git dir rides in this bundle, by workspace id — INCLUDING the ones no
+     * definition can name, which is the point: a repo with no remote is invisible to `definition.repositories`
+     * and is precisely the one an owner most wants carried by bytes. "root" is not listed; the workspace repo
+     * itself is not a nested repository and travels with the workspace files. */
+    repos: z.array(z.string()),
     // The declarable shape, exactly what a definition export emits, so the restore report reasons over the
     // same facts either door delivers.
     definition: SandboxDefinitionSchema,