@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/docs/dev/surfaces/secrets.md

@@ -0,0 +1,95 @@
+# Secrets surface: pattern-class vocabulary
+
+Repo-local addendum for the `secrets` surface registered in `.claude/surfaces.yml`:
+the yak redaction pass (`plugins/yak/yak-redact.ts`), its call site
+(`plugins/yak/yak-submit.ts`) and its tests (`tests/yak-redact.test.ts`). Format
+per the universal class core; class IDs use the prefix `S`.
+
+Seeded by hand from failure modes the pass's own header and tests already record,
+not from an audit run. Extend it when an audit of this surface names a new class.
+
+Tests are cited by a substring of their title, so `rg -F '<substring>' tests/yak-redact.test.ts`
+finds them.
+
+## S1: Pass-ordering shadowing
+
+**Shape:** a class whose pattern can match a run *inside* another class's token runs
+before that token's own class, so the inner class replaces only the embedded run.
+Triggered by adding a pass, or moving one, in the fixed pipeline order.
+
+**Why it kills:** the token's head survives in plaintext next to a `«redacted:…»`
+marker, so the output looks handled while a live credential prefix ships. A token's
+secret is base64url, so it can contain `-sk-`, `ghp_` and other shapes by chance.
+
+**Concrete fingerprint:** a `sib_` secret containing an `sk-key` run comes out as
+`sib_<orgId>_<head>-«redacted:sk-key»` instead of one `«redacted:sib-token»`. The
+mirror case: an earlier pass whose run is wider than its token swallows the anchor of
+text glued after it (`<token>Authorization: Basic <cred>` gives
+`«redacted:sib-token»: Basic <cred>`), so the later pass never fires.
+
+**Typical severity:** High. Critical when the surviving head carries the org id and a
+usable secret prefix.
+
+**Check mode:** hybrid. Deterministic for known instances: `embeds another class's shape`
+(the `sib-token` over `sk-key` and `github-token` case) and
+`classified once as sib-token, not as assignment` (a broader `assignment` claiming first),
+and `the glued-on text is left to the later passes` (the mirror case).
+LLM for a new or moved pass: could its pattern match inside another class's token alphabet?
+A new pass needs a test where a longer token embeds its shape.
+
+## S2: Partial-match plaintext tail
+
+**Shape:** a bounded value capture (`{1,N}`, a fixed-length token body, an anchored
+length) shorter than the real secret, so the match ends mid-secret.
+
+**Why it kills:** the first N characters become the marker and the remainder follows it
+in plaintext. That is worse than no redaction because the output looks handled. The
+bound is an input property the author does not control: the evidence field runs to
+20,000 chars, and issuers lengthen secrets. Widening is right only where the issuer's
+length is not fixed: `sib_` secrets are exactly 43 characters, so `SIB_TOKEN_RE` pins 43
+and leaves anything glued on to the later passes (S1).
+
+**Concrete fingerprint:** `«redacted:assignment»` directly followed by the rest of a
+secret. A later pass that would have consumed that tail can hide it again by declining the run
+because it starts with a marker (S3): `Authorization: Bearer «redacted:sk-key»<tail>`.
+
+**Typical severity:** High. Critical when the tail is most of the secret.
+
+**Check mode:** deterministic. `no plaintext run of the secret survives, even at 10,000 chars`,
+and `fully consumes a long JSON-quoted value` assert that no
+slice of the secret survives past the old bound. Its counterweight is
+`does not swallow the closing brace or a following key`: widening a capture must not eat
+the next JSON key. `runs on past an earlier class's marker` (auth-header and assignment) and
+`is an earlier class's marker, alone or with a tail` (conn-string) assert that a later pass
+still consumes a tail left after a marker.
+
+## S3: Marker re-match and double count
+
+**Shape:** a later pass treats an earlier pass's `«redacted:<class>»` marker as its own
+value, typically a quoted value under a governed name such as `"api_key": "«redacted:sk-key»"`.
+The fix is a guard in a pass that takes an arbitrary run as its value. A pass may decline
+only where declining leaves nothing but the marker and text that cannot be secret.
+`assignment` declines a value that is exactly one marker, bare or alone in quotes.
+`auth-header` declines an exact marker after a known scheme word. `conn-string` never
+declines: its scheme and host runs take whatever is pasted against them. A guard that
+declines any value that merely starts with a marker reintroduces S2, because whatever
+follows the marker in that run ships in plaintext. Redacting that run whole has its own
+failure: with no whitespace in between, the run swallows the name of the next
+assignment, and that assignment's value ships. `assignment` therefore redacts both
+readings. Prefer over-redaction and a double count to either leak.
+
+**Why it kills:** no plaintext leaks, but the marker is reclassified (here as the generic
+`assignment`) and counted twice. The class counts in the stderr summary line become wrong,
+and `redact()` stops being idempotent, so redacting already-redacted text changes it.
+
+**Concrete fingerprint:** a secret redacted as the generic `assignment` instead of its own
+class (`"api_key": "«redacted:sk-key»"` comes back as `«redacted:assignment»`), or a second
+`redact()` call that reports a nonzero total.
+
+**Typical severity:** Medium. Low when only the summary line is affected.
+
+**Check mode:** deterministic. `the marker itself is never re-matched` (every class's
+marker, in each position a guard covers), `redacting twice equals redacting once`, and
+`not re-redacted and reclassified as 'assignment'` pin the decline. The S2 tests named
+`runs on past an earlier class's marker`, `is an earlier class's marker, alone or with a tail`
+and `runs straight into another assignment` pin its limits.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@sibylline-labs/eris",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "A plugin-composed command-line tool in TypeScript on Bun, shipping eris yak",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sibylline-labs/eris.git"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "bin": {
+    "eris": "bin/eris.ts"
+  },
+  "exports": {
+    ".": "./src/main.ts",
+    "./sdk": "./src/sdk.ts",
+    "./sdk/testing": "./testing/index.ts",
+    "./yak-contract": "./packages/yak-contract/src/index.ts",
+    "./yak-redact": "./plugins/yak/yak-redact.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugins",
+    "packages/yak-contract/src",
+    "packages/yak-contract/schema",
+    "packages/yak-contract/package.json",
+    "testing",
+    "ts",
+    "docs",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.4.4",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "ajv": "8.20.0",
+    "bun-types": "1.4.4",
+    "typescript": "^6.0.3"
+  }
+}

package/packages/yak-contract/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sibylline-labs/yak-contract",
+  "version": "0.1.0",
+  "description": "The Eris Yaks wire contract, v2: Zod schemas, inferred types and the JSON Schema they emit",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schema": "./schema/yak-v2.schema.json"
+  },
+  "files": [
+    "src",
+    "schema"
+  ],
+  "scripts": {
+    "emit-schema": "bun scripts/emit-json-schema.ts",
+    "typecheck": "tsc --noEmit -p ."
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "bun-types": "1.4.4",
+    "typescript": "^6.0.3",
+    "zod-to-json-schema": "3.23.5"
+  }
+}

package/packages/yak-contract/schema/yak-v2.schema.json

@@ -0,0 +1,416 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Eris Yaks wire contract v2",
+  "$ref": "#/definitions/YakSubmission",
+  "definitions": {
+    "YakSubmission": {
+      "type": "object",
+      "properties": {
+        "schema_version": {
+          "type": "string",
+          "enum": [
+            "2.0.0"
+          ]
+        },
+        "verb": {
+          "type": "string",
+          "enum": [
+            "issue",
+            "suggest",
+            "fatal"
+          ]
+        },
+        "route": {
+          "type": "string",
+          "enum": [
+            "workspace",
+            "vendor"
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "body": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4000
+        },
+        "evidence": {
+          "type": "string",
+          "maxLength": 20000
+        },
+        "device_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "execution_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "idempotency_key": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "provenance": {
+          "type": "object",
+          "properties": {
+            "process": {
+              "type": "object",
+              "additionalProperties": {}
+            },
+            "device": {
+              "type": "object",
+              "additionalProperties": {}
+            },
+            "harness": {
+              "type": "object",
+              "additionalProperties": {}
+            },
+            "repo": {
+              "type": "object",
+              "properties": {
+                "target_repos": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  },
+                  "maxItems": 20
+                }
+              },
+              "additionalProperties": {}
+            },
+            "git": {
+              "type": "object",
+              "additionalProperties": {}
+            },
+            "execution": {
+              "type": "object",
+              "properties": {
+                "rung": {
+                  "type": "string",
+                  "enum": [
+                    "override",
+                    "session",
+                    "host-session",
+                    "shell-session",
+                    "shell",
+                    "ai-agent",
+                    "codex",
+                    "cursor"
+                  ]
+                }
+              },
+              "additionalProperties": {}
+            }
+          },
+          "additionalProperties": {}
+        }
+      },
+      "required": [
+        "schema_version",
+        "verb",
+        "route",
+        "summary",
+        "body",
+        "device_id",
+        "execution_id"
+      ],
+      "additionalProperties": true
+    },
+    "YakReceipt": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "idempotency_key": {
+          "type": "string"
+        },
+        "replay": {
+          "type": "boolean"
+        },
+        "contract_version": {
+          "type": "string",
+          "const": "2.0.0"
+        }
+      },
+      "required": [
+        "id",
+        "idempotency_key",
+        "replay",
+        "contract_version"
+      ],
+      "additionalProperties": true
+    },
+    "YakObservation": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "idempotency_key": {
+          "type": "string"
+        },
+        "verb": {
+          "type": "string",
+          "enum": [
+            "issue",
+            "suggest",
+            "fatal"
+          ]
+        },
+        "summary": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "received_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "processed",
+            "failed"
+          ]
+        },
+        "cluster_id": {
+          "type": "string"
+        },
+        "attempts": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "next_attempt_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "last_error": {
+          "type": "string"
+        },
+        "data": {
+          "type": "object",
+          "properties": {
+            "schema_version": {
+              "type": "string",
+              "enum": [
+                "2.0.0"
+              ]
+            },
+            "verb": {
+              "type": "string",
+              "enum": [
+                "issue",
+                "suggest",
+                "fatal"
+              ]
+            },
+            "route": {
+              "type": "string",
+              "enum": [
+                "workspace",
+                "vendor"
+              ]
+            },
+            "summary": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            },
+            "body": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4000
+            },
+            "evidence": {
+              "type": "string",
+              "maxLength": 20000
+            },
+            "device_id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            },
+            "execution_id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            },
+            "idempotency_key": {
+              "type": "string",
+              "maxLength": 128
+            },
+            "provenance": {
+              "type": "object",
+              "properties": {
+                "process": {
+                  "type": "object",
+                  "additionalProperties": {}
+                },
+                "device": {
+                  "type": "object",
+                  "additionalProperties": {}
+                },
+                "harness": {
+                  "type": "object",
+                  "additionalProperties": {}
+                },
+                "repo": {
+                  "type": "object",
+                  "properties": {
+                    "target_repos": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 200
+                      },
+                      "maxItems": 20
+                    }
+                  },
+                  "additionalProperties": {}
+                },
+                "git": {
+                  "type": "object",
+                  "additionalProperties": {}
+                },
+                "execution": {
+                  "type": "object",
+                  "properties": {
+                    "rung": {
+                      "type": "string",
+                      "enum": [
+                        "override",
+                        "session",
+                        "host-session",
+                        "shell-session",
+                        "shell",
+                        "ai-agent",
+                        "codex",
+                        "cursor"
+                      ]
+                    }
+                  },
+                  "additionalProperties": {}
+                }
+              },
+              "additionalProperties": {}
+            }
+          },
+          "required": [
+            "schema_version",
+            "verb",
+            "route",
+            "summary",
+            "body",
+            "device_id",
+            "execution_id"
+          ],
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "id",
+        "idempotency_key",
+        "verb",
+        "summary",
+        "source",
+        "received_at",
+        "status",
+        "attempts",
+        "data"
+      ],
+      "additionalProperties": true
+    },
+    "YakCluster": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "fatal",
+            "report"
+          ]
+        },
+        "canonical_summary": {
+          "type": "string"
+        },
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "observation_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "first_seen": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "last_seen": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "current_issue_id": {
+          "type": "string"
+        },
+        "current_issue_identifier": {
+          "type": "string"
+        },
+        "issue_history": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "issue_id": {
+                "type": "string"
+              },
+              "issue_identifier": {
+                "type": "string"
+              },
+              "linked_at": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "closed_observed_at": {
+                "type": "string",
+                "format": "date-time"
+              }
+            },
+            "required": [
+              "issue_id",
+              "issue_identifier",
+              "linked_at"
+            ],
+            "additionalProperties": true
+          },
+          "default": []
+        }
+      },
+      "required": [
+        "id",
+        "kind",
+        "canonical_summary",
+        "observation_count",
+        "first_seen",
+        "last_seen"
+      ],
+      "additionalProperties": true
+    }
+  }
+}

package/packages/yak-contract/src/index.ts

@@ -0,0 +1 @@
+export * from "./v2";