@pithy-sh/secrets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @pithy-sh/secrets
+
+Encrypted secret storage for Pithy. One dedicated store per environment, a worker-only master key, automatic at-rest key rotation, and the `pithy secrets` CLI to manage it.
+
+```sh
+pithy add secrets
+```
+
+**Documentation: [pithy.sh/docs/capabilities/secrets](https://pithy.sh/docs/capabilities/secrets).** Overview, adding it, using it, and the reference: the two backends, keyspaces, scope, rotation, the master key, dev values.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pithy-sh/secrets",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/secrets"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/core": "workspace:*",
+    "comment-json": "^5.0.0",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,48 @@
+{
+  "name": "secrets",
+  "package": "@pithy-sh/secrets",
+  "requiredBindings": [{ "type": "d1", "name": "SECRETS" }, { "type": "secret", "name": "SECRETS_ENCRYPTION_KEYS" }],
+  "optionalCapabilities": ["controlplane", "audit"],
+  "migrationNamespace": "secrets",
+  "secrets": [
+    {
+      "name": "SECRETS_ENCRYPTION_KEYS",
+      "origin": {
+        "kind": "minted",
+        "recipe": {
+          "kind": "encryptionConfig"
+        }
+      },
+      "rotation": {
+        "kind": "local"
+      }
+    },
+    {
+      "name": "CLOUDFLARE_API_TOKEN",
+      "origin": {
+        "kind": "helped",
+        "issuer": "cloudflare",
+        "needs": { "cloudflare": ["secrets:read", "secrets:write"] },
+        "documentation": "https://developers.cloudflare.com/fundamentals/api/get-started/create-token/"
+      },
+      "rotation": {
+        "kind": "provider",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/api/resources/user/subresources/tokens/methods/update/"
+      }
+    }
+  ],
+  "whenToEnable": "Encrypted secret storage with a worker-only master key and automatic at-rest key rotation. Auth's token-signing key lives here.",
+  "configOptions": [
+    {
+      "key": "registry",
+      "default": {},
+      "describe": "Your secrets, keyed by name — each declaring where it lives (`backend`), whether its value is the same everywhere (`scope`), whether a rotator may manage it (`rotatable`), how it is read (`valueType`, plus a Zod schema for `json`), and — optionally, together — how it comes to exist (`origin`) and how it is replaced (`rotation`), which is what lets a tool tell you *run this* or *get it here* instead of *not set*. Empty because the contents are yours and `pithy add` cannot invent them. Both the worker's `secretsStore` and the `pithy secrets` CLI read this object, so a secret that is not declared here does not exist. Fill it in before you store anything — see @pithy-sh/secrets' README."
+    },
+    {
+      "key": "rotationIntervalDays",
+      "default": 30,
+      "describe": "How often the at-rest encryption key rotates. The secrets manager re-encrypts every stored secret on this cadence; raise it to rotate less often, lower it to rotate more aggressively."
+    }
+  ]
+}

package/src/admin/health.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type CapabilityHealth, defineCapabilityHealth } from "@pithy-sh/core/src/controlPlane/discovery/health";
+import { secretsStatusDatabase } from "../data/statusDb";
+import { SECRETS_STATUS_READ_SCOPE } from "../http/guards";
+import type { SecretRegistry } from "../registry";
+import { readSecretStatus, type SecretStatusEntry, type SecretsStatusDb } from "./status";
+
+/**
+ * What this capability contributes to its manifest entry: one number, so a management client can say
+ * "3 secrets need rotating" from the read it already made (#317).
+ *
+ * ## Why a count belongs on the manifest and the list does not
+ *
+ * The list is `GET {base}/admin/status`, and it stays there. What a rail needs is whether the detail is
+ * worth fetching, and that is one scalar. Anything more — which secrets, since when — grows with the
+ * adopter's registry and would turn a discovery read into a data API.
+ *
+ * ## What it costs, stated
+ *
+ * Exactly what the status read costs, because it *is* the status read: one `where name in (...)` against
+ * `pithy_secrets_system_secrets`, where `name` is unique, and one grouped `where name in (...)` against
+ * `pithy_secrets_rotations`, where `name` is indexed (`pithySecretsRotationsNameIdx`). Both are bounded
+ * by how many secrets the composed registry *declares* — a number in the adopter's source — and never by
+ * how many rows they hold. That is what `cost: "indexed"` claims, and it is the whole reason this may
+ * sit on the most frequently fetched read the seam serves.
+ *
+ * ## One definition of late
+ *
+ * The count is derived from {@link readSecretStatus} rather than from a second query that re-decides
+ * what overdue means. A secret whose registry entry declares no cadence, or that has nothing to measure
+ * from, reports `overdue: null` there and is not counted here: nobody has said what late means for it,
+ * and counting it would be an opinion the capability does not hold.
+ */
+
+/** The key the count appears under. Exported so a client and a test name it from one place. */
+export const SECRETS_DUE_FOR_ROTATION = "secretsDueForRotation";
+
+/**
+ * How many of these entries are past their declared cadence — the one definition of "due", read by
+ * the manifest count here and by the status route's own audit metadata.
+ *
+ * `overdue === true` and never merely truthy: the third state is null — nobody has said what late means
+ * for that secret — and folding it into "not overdue" would be the same mistake as reporting a withheld
+ * number as zero.
+ *
+ * **An unreadable entry is not counted, and the count is still a number (`#387`).** Before the per-row
+ * guard, one malformed row threw out of `readSecretStatus` and this capability reported `unavailable` for
+ * the whole manifest key — `#350` working exactly as designed, and still the wrong answer, because the
+ * other secrets' freshness was knowable and went unreported. A secret whose row will not decode is now in
+ * the same position as one that declares no cadence: nobody can say whether it is late, so it is not
+ * asserted to be. That is a smaller lie than counting it either way, and a much smaller one than
+ * withholding the number.
+ */
+export function dueForRotation(entries: readonly SecretStatusEntry[]): number {
+  return entries.filter((entry) => entry.state === "readable" && entry.status.overdue === true).length;
+}
+
+/** How many declared secrets are past the cadence their registry entry declares. */
+export async function countSecretsDueForRotation(
+  db: SecretsStatusDb,
+  registry: SecretRegistry,
+  now?: Date,
+): Promise<number> {
+  return dueForRotation(await readSecretStatus(db, registry, now ? { now } : {}));
+}
+
+/**
+ * The capability's health summary, over the registry it actually composed.
+ *
+ * A thunk for the same reason the status routes take one: the set worth reporting is every capability's
+ * combined registry, and that only exists after `compose` has run.
+ */
+export function secretsHealth(registry: () => SecretRegistry): CapabilityHealth {
+  return defineCapabilityHealth({
+    keys: [
+      {
+        key: SECRETS_DUE_FOR_ROTATION,
+        kind: "count",
+        states: null,
+        // The scope the status read is already behind. A count is a smaller disclosure than the listing
+        // it summarizes, but it is a disclosure of the same thing — which credentials are stale is a map
+        // of where to push — so an adopter who withheld the listing withholds the number with it.
+        scope: SECRETS_STATUS_READ_SCOPE,
+        cost: "indexed",
+        summary: "Secrets past the rotation cadence their registry entry declares.",
+      },
+    ],
+    read: async (c) => ({
+      [SECRETS_DUE_FOR_ROTATION]: await countSecretsDueForRotation(secretsStatusDatabase(c), registry()),
+    }),
+  });
+}