feat(passkeys): registration ceremony (#38)

A signed-in customer can register a passkey. Signing in with one is #39 and the management screen is #40, so nothing reads these credentials yet.

The name column arrives here rather than in #37. That issue listed the columns the ceremony needs and this one is for the person: #40 shows a list and offers to revoke from it, and "phone" against "laptop" is the only thing that makes two rows tellable apart. Without it a customer revoking a credential is choosing between identical entries. The customer may name it, and otherwise it is derived from the authenticator's transports — a hint rather than a fact, so the defaults are deliberately vague. "This device" is honest about a platform authenticator in a way that guessing at a model name would not be.

Single use is enforced by deleting the challenge and treating the delete as the check, in one statement with the expiry condition. A replayed response finds nothing to delete and is refused, and two requests racing cannot both see the row and both proceed. Beginning a second registration replaces any in-flight challenge for that customer, so pressing the button twice cannot leave the first one usable.

The challenge is consumed before the response is verified, deliberately. A failed attempt must not leave one available for a second try, so an invalid response costs the ceremony rather than merely failing it.

Never started, already used and expired all answer the same way. From the server they are one condition — no challenge this customer may still complete — and distinguishing them would tell someone guessing which guess was closest.

excludeCredentials stops the same authenticator being enrolled twice, but it is a hint the browser may ignore, so the unique constraint on credential_id is what actually holds. Hitting it answers 409: the credential is already registered, which is not a failure of anything.

userID is the customer id rather than the email. A userID is meant to be stable and opaque, and an email is neither — a customer changing theirs would otherwise look like a different person to their own authenticator.

Discoverable credentials are requested as preferred rather than required, because #39 wants sign-in without the customer first saying who they are, and an authenticator that cannot store one should still be usable here.

Mounted before /api/customers, like the addresses router: Express matches mounts in order and the broader prefix would otherwise swallow these.

Verified: tsc clean for src and tests, lint 0 errors with no new warnings, 514 unit tests across 35 suites — twenty new, covering the naming rules. The schema mirror gains the name column, placed where kysely-codegen would put it.

Not verified: neither migration has been run against a database, and the ceremony itself cannot be exercised without a browser and an authenticator. What CI can prove is that the routes exist, are wrapped, and refuse an unauthenticated caller; what it cannot prove is a real attestation, which needs a device.

Closes #38

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/src/passkeys/credentialName.ts

@@ -0,0 +1,48 @@
+/**
+ * A name for a passkey the customer did not name themselves (#38).
+ *
+ * The management screen (#40) lists credentials and offers to revoke them, so
+ * two entries that read identically are a screen where the customer cannot tell
+ * which device they are removing. A default that says something is the
+ * difference between "Passkey, Passkey, Passkey" and a list worth showing.
+ *
+ * Derived from the authenticator's transports, which is the only thing the
+ * ceremony learns about the device. It is a hint rather than a fact — the
+ * browser reports what the authenticator claims — so these are deliberately
+ * vague. "This device" is honest about a platform authenticator in a way that
+ * guessing "MacBook" would not be.
+ */
+
+/** The fallback when the authenticator reports nothing usable. */
+export const GENERIC_CREDENTIAL_NAME = 'Passkey';
+
+export function defaultCredentialName(transports: readonly string[] | null | undefined): string {
+  if (!transports || transports.length === 0) return GENERIC_CREDENTIAL_NAME;
+
+  // Checked in this order because an authenticator can report several. A phone
+  // used as a cross-device passkey reports `hybrid` and often `internal` too,
+  // and "Phone or tablet" is the more useful of the two readings — `internal`
+  // alone means the authenticator built into the machine being used.
+  if (transports.includes('hybrid')) return 'Phone or tablet';
+  if (transports.includes('internal')) return 'This device';
+  if (transports.some((t) => t === 'usb' || t === 'nfc' || t === 'ble')) return 'Security key';
+
+  return GENERIC_CREDENTIAL_NAME;
+}
+
+/**
+ * The customer's own name for a passkey, or null when they gave none.
+ *
+ * Trimmed, because a name of spaces is a name nobody can read in a list, and
+ * bounded because this is rendered — a customer is naming their laptop, not
+ * writing prose, and an unbounded string in a table cell is a layout problem
+ * rather than an expressive one.
+ */
+export const MAX_CREDENTIAL_NAME_LENGTH = 64;
+
+export function readCredentialName(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (trimmed === '') return null;
+  return trimmed.slice(0, MAX_CREDENTIAL_NAME_LENGTH);
+}