@supersuit/suit-identity 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release, extracted on 2026-10-17 from two copies: Supersuit's `freedom-suit-id.mjs` (the Mac that mints and signs) and the Supersuit account server's `suit-identity.mjs` (the checker). Suit IDs from a first Ed25519 key, the signed hash-chained key log (genesis, add-key, retire-key) and its replay, canonical JSON, the handle rule (8 to 32, no exceptions, reserved names), and a CLI (`id`, `verify`, `check-handle`). Pinned by the test vector both callers assert (seed 32 x 0x09).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+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

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @supersuit/suit-identity
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Durable, key-based identities. A suit's ID is derived from its first Ed25519 key and never changes. Every later key change (a second device added, a lost one retired) is an entry in a signed, hash-chained log that anyone can replay to learn which keys are active, without trusting whoever handed them the log. A handle is the changeable human name that points at an ID.
+
+Zero dependencies (Node's own crypto), no file or network access: you keep the keys and the log wherever you like.
+
+```bash
+npm install @supersuit/suit-identity
+```
+
+## Library
+
+```js
+import { newDeviceKey, genesisEntry, nextEntry, verifyLog, signEntry, verifySig, checkHandle, suitIdFrom } from "@supersuit/suit-identity";
+
+const mac = newDeviceKey();                       // { priv, pub }; keep priv private
+const log = [genesisEntry({ priv: mac.priv, device: "mac", at: new Date().toISOString() })];
+const phone = newDeviceKey();
+log.push(nextEntry(log, { op: "add-key", key: phone.pub, device: "phone", at: new Date().toISOString() }, mac.priv));
+
+verifyLog(log);           // { ok: true, suit: "ss1...", keys: [mac.pub, phone.pub] }
+checkHandle("garysheng"); // { ok: true }
+checkHandle("gary");      // { ok: false, why: "a handle is at least 8 characters, with no exceptions" }
+
+const claim = signEntry({ op: "claim", handle: "garysheng", suit: log[0].suit, at: new Date().toISOString() }, mac.priv);
+```
+
+Options, for another system: `suitIdFrom(pub, { prefix, length })` (default `ss1` and 16 characters), `verifyLog(log, { idOptions })`, `checkHandle(h, { min, max, reserved })` (default 8, 32 and Supersuit's reserved names).
+
+## CLI
+
+```bash
+suit-identity id <public-key>          # the suit ID that key founds
+suit-identity verify <log.jsonl|->     # replay a key log, one JSON entry per line
+suit-identity check-handle <handle>
+```
+
+Add `--json` for machine output. Exit codes: 0 ok, 1 refused, 2 usage.
+
+## Who uses it
+
+Supersuit's Macs mint and sign with it (`freedom-suit-id.mjs`), and the Supersuit account server checks every suit and name claim with it. The test vector in `test/` (seed 32 x 0x09) is the exact bytes both agree on.

package/bin/suit-identity.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// suit-identity: check suit IDs, key logs and handles from the command line.
+//   suit-identity id <public-key>            the suit ID that key founds
+//   suit-identity verify <log.jsonl|->       replay a key log (one JSON entry per line); prints the active keys
+//   suit-identity check-handle <handle>      is this a valid handle
+// Add --json for machine output. Exit codes: 0 ok, 1 refused, 2 usage.
+import { readFileSync } from "node:fs";
+import { checkHandle, suitIdFrom, verifyLog } from "../src/index.mjs";
+
+const [cmd, arg, ...rest] = process.argv.slice(2);
+const json = [arg, ...rest].includes("--json");
+const say = (obj, line) => console.log(json ? JSON.stringify(obj) : line);
+const usage = () => { console.error("usage: suit-identity id <public-key> | verify <log.jsonl|-> | check-handle <handle> [--json]"); process.exit(2); };
+
+if (!arg || arg === "--json") usage();
+if (cmd === "id") { const suit = suitIdFrom(arg); say({ suit }, suit); process.exit(0); }
+if (cmd === "verify") {
+  let log;
+  try { log = readFileSync(arg === "-" ? 0 : arg, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)); }
+  catch (e) { say({ ok: false, why: `could not read the log: ${e.message}` }, `could not read the log: ${e.message}`); process.exit(1); }
+  const v = verifyLog(log);
+  say(v, v.ok ? `${v.suit}: verifies, ${v.keys.length} active key${v.keys.length === 1 ? "" : "s"}\n${v.keys.join("\n")}` : `does not verify: ${v.why}`);
+  process.exit(v.ok ? 0 : 1);
+}
+if (cmd === "check-handle") { const r = checkHandle(arg); say(r, r.ok ? `${arg} is a valid handle` : r.why); process.exit(r.ok ? 0 : 1); }
+usage();

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@supersuit/suit-identity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Durable, key-based identities for Supersuit suits: a suit ID derived from its first key, a signed key log anyone can replay, and the handle rule.",
+  "type": "module",
+  "bin": {
+    "suit-identity": "bin/suit-identity.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SupersuitUp/suit-identity.git"
+  },
+  "dependencies": {}
+}

package/src/index.mjs

@@ -0,0 +1,109 @@
+// @supersuit/suit-identity: durable, key-based identities. A suit's ID is derived from its first
+// Ed25519 key and never changes; every later key change is an entry in a signed, hash-chained log that
+// anyone can replay to learn which keys are active, without trusting whoever handed them the log.
+// A handle is the changeable, human name that points at an ID.
+//
+// One copy of this logic for every caller: the Mac that mints and signs (Supersuit's
+// freedom-suit-id.mjs) and the server that checks (the Supersuit account server). Zero dependencies;
+// Node's own crypto. Pure: no file or network access, so each caller keeps its own storage.
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from "node:crypto";
+
+/** JSON with object keys sorted at every depth, no whitespace, undefined fields dropped: the bytes
+ *  every signature covers, so the same payload signs the same way on every machine. */
+export function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map((v) => (v === undefined ? "null" : canonical(v))).join(",") + "]";
+  return "{" + Object.keys(value).filter((k) => value[k] !== undefined).sort().map((k) => JSON.stringify(k) + ":" + canonical(value[k])).join(",") + "}";
+}
+
+const privObj = (priv) => createPrivateKey({ key: Buffer.from(priv, "base64url"), format: "der", type: "pkcs8" });
+const pubObj = (pub) => createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: pub }, format: "jwk" });
+
+/** A new Ed25519 key. `priv` is pkcs8 DER, base64url (keep it private); `pub` is the raw key, base64url. */
+export function newDeviceKey() {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const priv = privateKey.export({ format: "der", type: "pkcs8" }).toString("base64url");
+  return { priv, pub: createPublicKey(privObj(priv)).export({ format: "jwk" }).x };
+}
+
+/** The public half of a pkcs8 base64url private key. */
+export const publicKeyOf = (priv) => createPublicKey(privObj(priv)).export({ format: "jwk" }).x;
+
+// Crockford base32, lowercase: no i, l, o or u, so an ID read aloud or copied by hand survives.
+const CROCKFORD = "0123456789abcdefghjkmnpqrstvwxyz";
+function base32(bytes) {
+  let bits = 0, value = 0, out = "";
+  for (const b of bytes) {
+    value = (value << 8) | b; bits += 8;
+    while (bits >= 5) { out += CROCKFORD[(value >>> (bits - 5)) & 31]; bits -= 5; }
+  }
+  if (bits > 0) out += CROCKFORD[(value << (5 - bits)) & 31];
+  return out;
+}
+
+/** The durable ID of the suit whose first key is `pub`: a prefix plus `length` Crockford base32
+ *  characters of the key's sha256 (default "ss1" + 16, which is 80 bits). */
+export const suitIdFrom = (pub, { prefix = "ss1", length = 16 } = {}) =>
+  prefix + base32(createHash("sha256").update(Buffer.from(pub, "base64url")).digest()).slice(0, length);
+
+/** `payload` with a `sig` field: Ed25519 over its canonical bytes. */
+export const signEntry = (payload, priv) => ({ ...payload, sig: sign(null, Buffer.from(canonical(payload)), privObj(priv)).toString("base64url") });
+
+/** Does `sig` verify over the canonical bytes of `payload` with public key `pub`? Never throws. */
+export function verifySig(payload, sig, pub) {
+  try { return verify(null, Buffer.from(canonical(payload)), pubObj(pub), Buffer.from(String(sig ?? ""), "base64url")); } catch { return false; }
+}
+
+const entryHash = (e) => createHash("sha256").update(canonical(e)).digest("hex");
+const bodyOf = (e) => { const { sig, ...rest } = e; return rest; };
+
+/** The genesis entry of a new suit, self-signed by its first key. */
+export function genesisEntry({ priv, device, at, idOptions } = {}) {
+  const key = publicKeyOf(priv);
+  return signEntry({ v: 1, op: "genesis", suit: suitIdFrom(key, idOptions), key, device, at, prev: null }, priv);
+}
+
+/** The next log entry after `log` (op "add-key" or "retire-key"), chained to its last entry and
+ *  signed by `priv`, which must be a key still active in the log for the entry to verify. */
+export function nextEntry(log, { op, key, device, at }, priv) {
+  return signEntry({ v: 1, op, suit: log[0].suit, key, device, at, prev: entryHash(log.at(-1)) }, priv);
+}
+
+/** Replay a log. ok only when the genesis is self-signed by the key its suit ID derives from, and
+ *  every later entry is chained to the one before and signed by a key active at that point. Returns
+ *  { ok: true, suit, keys } (the keys active at the end) or { ok: false, why }. */
+export function verifyLog(log, { idOptions } = {}) {
+  const no = (why) => ({ ok: false, why });
+  if (!Array.isArray(log) || !log.length) return no("the log is empty");
+  const g = log[0];
+  if (g?.op !== "genesis" || g.prev !== null) return no("the first entry is not a genesis");
+  if (suitIdFrom(g.key, idOptions) !== g.suit) return no("the genesis suit is not the one its key derives");
+  if (!verifySig(bodyOf(g), g.sig, g.key)) return no("the genesis signature does not verify");
+  const active = new Set([g.key]);
+  for (let i = 1; i < log.length; i++) {
+    const e = log[i];
+    if (e.suit !== g.suit) return no(`entry ${i} names another suit`);
+    if (e.prev !== entryHash(log[i - 1])) return no(`entry ${i} is not chained to entry ${i - 1}`);
+    if (![...active].some((k) => verifySig(bodyOf(e), e.sig, k))) return no(`entry ${i} is not signed by an active key`);
+    if (e.op === "add-key") active.add(e.key);
+    else if (e.op === "retire-key") { active.delete(e.key); if (!active.size) return no(`entry ${i} retires the last key`); }
+    else return no(`entry ${i} has an unknown op ${e.op}`);
+  }
+  return { ok: true, suit: g.suit, keys: [...active] };
+}
+
+/** Names that read as the operator of the system speaking. Only names at or above the minimum length
+ *  need listing. Supersuit's set; pass your own as `reserved`. */
+export const RESERVED = Object.freeze(["supersuit", "supersuits", "continental", "continentalworks", "administrator", "postmaster", "hostmaster", "webmaster", "official", "security", "helpdesk", "freedomapp", "multiversal", "cofounders"]);
+
+/** The handle rule. Defaults are Supersuit's: 8 to 32 characters with no exceptions (decided
+ *  2026-10-17), lowercase letters, digits and single hyphens, reserved names refused. */
+export function checkHandle(h, { min = 8, max = 32, reserved = RESERVED } = {}) {
+  const no = (why) => ({ ok: false, why });
+  if (typeof h !== "string") return no("a handle is text");
+  if (h.length < min) return no(`a handle is at least ${min} characters, with no exceptions`);
+  if (h.length > max) return no(`a handle is at most ${max} characters`);
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(h)) return no("a handle is lowercase letters, digits and single hyphens, starting and ending with a letter or digit");
+  if (reserved.includes(h)) return no(`${h} is reserved`);
+  return { ok: true };
+}