Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/incoming-arrival-reconciliation-order.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"hypercerts-entryway": patch
---

For operators recovering pending incoming arrivals, internal reconciliation now resumes an accepted unpublished PLC handoff before destination creation when both admissions are saved. Recovery at the exact saved destination move continues without republishing the handoff or requiring a new source credential. Uncertain writes still require operator isolation and drain approval; this does not expose public migration routes or activate pending accounts.
62 changes: 62 additions & 0 deletions .changeset/incoming-handoff-provisioning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
---
"hypercerts-entryway": minor
---

For maintainers assembling the still-dormant incoming flow, this adds the code that turns a prepared arrival into a
provisioned, still-pending destination. It reserves the destination repository
key, accepts the source-signed authority handoff, and creates the destination
account ahead of data transfer. Nothing here is reachable yet: no route is
mounted, so an operator sees no behaviour change until the public API is
assembled.

Dormant preparation now checks the destination browser session, origin/CSRF and
fresh OTP before reserving an enrolled destination. It validates the configured
PLC history and retains the exact signed predecessor and CID, including legacy
`create` identities. Existing rotation priority is preserved; the Entryway hot key
is added only within the protocol limit. This remains preparation evidence, not
source ownership or activation readiness.

Dormant authenticated admission now verifies the source repository JWT's document
identity, controller, method, audience and replay identity, with a maximum
300-second lifetime. Handoff admission and signed public bytes commit together
before directory dispatch. Lost responses retain the existing isolation/drain
recovery requirement; saved-owner continuation reuses accepted bytes without a
new source credential after key cutover. Creation admission reuses registration's
real invitation producer atomically, without copying raw invite codes into incoming
journals. Supported creation fields are handle and optional DID, email and invite;
other stock optional fields are explicitly rejected. Dormant creation continuation
now uses the saved owner and admission without a new source JWT or arrival code.
It journals the exact destination move, observes and pauses the backend using
configured administrator credentials, and atomically binds the pending account
with invitation completion. Lost creation or pause responses still require
verified isolation/drain recovery. A published move without a backend stays
pending without blind creation or fresh key reservation. Public migration
qualification remains separate work.

What this will mean once it is wired:

- The destination PDS is asked for a public repository key without any Entryway
credential. Only the public key is stored; the private key stays on that PDS.
Early cutover, separate deactivation and retained recovery obligations are what
this flow claims — it is **not** an independent interoperability claim.
- The arrival is journaled before the destination PDS is contacted, so an
interrupted preparation leaves a recorded obligation instead of a silent retry
on a different host.
- The source-signed handoff is checked against the expected predecessor, the
approved key order and the unchanged source service, verification key and
aliases. A full key list is rejected rather than truncated, and removing or
reordering keys is refused. The accepted operation is stored before it is sent
directly to the configured PLC directory, and publication is only claimed once
canonical history shows it.
- Destination creation requires a fresh source credential scoped to account
creation; a handoff-scoped credential cannot authorize it. Account creation
publishes Entryway's destination move, so the account is briefly active before
it is deactivated. The two steps stay distinct, and the result is a pending
arrival rather than a usable account.
- Every unresolved step — an unobserved handoff, a creation whose response was
lost, a deactivation that did not take effect — keeps the arrival pending with
a stable recovery code. None of these are repaired by signing a different
identity operation.

Until the remaining readiness work lands, no transfer credentials are issued and
no arrival becomes active.
21 changes: 21 additions & 0 deletions .changeset/incoming-signed-destination-move.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
"hypercerts-entryway": patch
---

For maintainers assembling dormant incoming migration, destination creation now
receives the signed PLC move rather than an unsigned variant. This fixes the
internal payload contract; it does not qualify full stock-PDS migration.

Internal behavior before public wiring:

- The destination move is journaled and dispatched as the signed operation the
PLC directory will publish. An interrupted attempt re-dispatches those exact
bytes rather than an unsigned variant of them.
- A journaled operation's CID now matches the directory head, because both cover
the signed bytes. Recorded bytes and their CID agree, so an exact retry remains
idempotent.
- A PLC signature is public data. It is no longer mistaken for private key
material, and a journaled operation must now carry one; private key material is
still refused.

No schema change, public route or readiness claim is added by this change.
5 changes: 5 additions & 0 deletions .changeset/lazy-incoming-account-signing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"hypercerts-entryway": patch
---

For operators using incoming account migration, destination reservation and administrator operations no longer initialize the account-token signing key unnecessarily. Invalid signing keys are reported through awaited account-token operations instead of causing an unhandled rejection during client construction. No configuration change is required.
76 changes: 76 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ jobs:
run: npm run build
- name: test:unit
run: npm run test:unit
- name: test:incoming-reconciliation
run: npm run test:incoming-reconciliation
- name: test:incoming-helpers
run: npm run test:incoming-helpers
- name: test:ci-lifecycle
Expand Down Expand Up @@ -77,6 +79,72 @@ jobs:
test "$DOCKER_CONTEXT" = default
docker --context default compose version
deno --version
- name: Diagnose hosted package network
continue-on-error: true
timeout-minutes: 3
run: &package-network-diagnostics |
# CI maintainers: compare runner, container and fresh build networking.
python3 - <<'PYTHON'
import subprocess
import uuid

probe = r"""
const dns = require('node:dns').promises;
const http = require('node:http');
const https = require('node:https');
(async () => {
for (const host of ['archive.ubuntu.com', 'security.ubuntu.com', 'deb.nodesource.com']) {
try {
await Promise.race([dns.lookup(host), new Promise((_, reject) => setTimeout(() => reject({code: 'DNS_TIMEOUT'}), 5000).unref())]);
console.log('dns host=' + host + ' status=resolved');
} catch (error) {
console.log('dns host=' + host + ' code=' + (error.code || 'DNS_FAILED'));
process.exitCode = 1;
}
}
for (const url of ['http://archive.ubuntu.com/ubuntu/dists/noble/InRelease', 'https://archive.ubuntu.com/ubuntu/dists/noble/InRelease', 'http://security.ubuntu.com/ubuntu/dists/noble-security/InRelease', 'https://security.ubuntu.com/ubuntu/dists/noble-security/InRelease', 'https://deb.nodesource.com/node_24.x/dists/nodistro/InRelease']) {
await new Promise(resolve => {
const request = (url.startsWith('https:') ? https : http).request(url, {method: 'HEAD'}, response => {
console.log('http url=' + url + ' status=' + response.statusCode);
if (response.statusCode < 200 || response.statusCode >= 400) process.exitCode = 1;
response.destroy();
resolve();
});
const timer = setTimeout(() => request.destroy(Object.assign(new Error(), {code: 'PROBE_TIMEOUT'})), 5000);
request.on('close', () => clearTimeout(timer));
request.on('error', error => {
console.log('http url=' + url + ' code=' + (error.code || 'REQUEST_FAILED'));
process.exitCode = 1;
resolve();
});
request.end();
});
}
})();
"""
image = 'mcr.microsoft.com/playwright:v1.58.2-noble'
probe = ' '.join(probe.splitlines())
container = 'hypercerts-entryway-network-probe-' + uuid.uuid4().hex
commands = [
('runner', ['node', '-e', probe], None),
('container', ['docker', '--context', 'default', 'run', '--rm', '--name', container, '--entrypoint', 'node', image, '-e', probe], None),
('build', ['docker', '--context', 'default', 'build', '--no-cache', '--progress=plain', '-'],
'FROM ' + image + '\nRUN node -e ' + "'" + probe.replace("'", "'\"'\"'") + "'\n"),
]
failed = False
for label, command, dockerfile in commands:
print('network-probe context=' + label + ' status=started', flush=True)
try:
result = subprocess.run(command, input=dockerfile, text=True, timeout=55)
status = result.returncode
except subprocess.TimeoutExpired:
status = 124
if label == 'container':
subprocess.run(['docker', '--context', 'default', 'rm', '--force', container], timeout=10, check=True)
print('network-probe context=' + label + ' exit=' + str(status), flush=True)
failed = failed or status != 0
raise SystemExit(int(failed))
PYTHON
- name: Register owned project before provisioning
run: |
python3 scripts/ci-ownership.py init "$CI_OWNERSHIP_MANIFEST"
Expand Down Expand Up @@ -149,6 +217,10 @@ jobs:
test "$DOCKER_CONTEXT" = default
docker --context default compose version
deno --version
- name: Diagnose hosted package network
continue-on-error: true
timeout-minutes: 3
run: *package-network-diagnostics
- name: Register owned project before provisioning
run: |
python3 scripts/ci-ownership.py init "$CI_OWNERSHIP_MANIFEST"
Expand Down Expand Up @@ -197,6 +269,10 @@ jobs:
test "$DOCKER_CONTEXT" = default
docker --context default compose version
deno --version
- name: Diagnose hosted package network
continue-on-error: true
timeout-minutes: 3
run: *package-network-diagnostics
- name: Register owned project before provisioning
run: |
python3 scripts/ci-ownership.py init "$CI_OWNERSHIP_MANIFEST"
Expand Down
11 changes: 11 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,17 @@ binds login and may use a different address from the source. Whole-PDS joining
imports established DID/email associations. Neither route adds a bespoke ownership
proof or permits email matching alone to establish DID authority.

The [incoming migration contract](incoming-migration.md#c4-client-managed-migration-contract-accepted)
was updated by user decision on 2026-11-11: the client owns record/blob transfer,
checking its chosen state and choosing when to request activation. Entryway guards
authorized activation using canonical identity/custody, placement, saved-user binding,
backend state and durable operation ownership. It does not certify a final source
head or full inventory, or provide a global verification-to-activation write barrier.
Concurrent/later source writes and missing blobs may not transfer. Early PLC cutover,
create-active then pause, pending-account guards and isolation/drain recovery remain
required. This is design acceptance, not completion of credentials, mounted public
routes or stock-PDS public journey/recovery qualification.

The architecture checker resolves real imports, including TS/MJS aliases, dynamic
imports and require. It rejects extra ports, raw SQL/SMTP/Better Auth access outside
owned boundaries, feature-internal imports, runtime cycles and impure rule modules.
Expand Down
38 changes: 26 additions & 12 deletions docs/data-custody.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Data model, identity custody and migration

Status: current storage facts plus accepted domain contracts and implementation gaps.
Incoming migration design updated: 2026-11-04.
Incoming migration design updated: 2026-11-11.
See [architecture](architecture.md) for domain ownership and [delivery reference](delivery-plan.md) for delivery gates.

## 1. Account identity and ownership
Expand Down Expand Up @@ -85,18 +85,18 @@ The table below records current storage, not the full approved target. Internal
refactoring does not require upgrading existing databases; public account migration
and existing ePDS deployment conversion remain separate requirements.

| State | Domain or system owner | Current representation |
| -------------------------------------- | ----------------------------------- | --------------------------------------------------------------------- |
| Account identity and status | Accounts | `accounts`, keyed by DID |
| Login identity binding | Accounts | `account_bindings`, unique DID and nonunique Better Auth user |
| State | Domain or system owner | Current representation |
| -------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account identity and status | Accounts | `accounts`, keyed by DID |
| Login identity binding | Accounts | `account_bindings`, unique DID and nonunique Better Auth user |
| Email and handle claims | Accounts | Primary claims may repeat across DIDs and coexist with a pending primary-email change; backup claims cannot overlap primary claims, and backup and pending claims are mutually exclusive |
| Verified browser identity and sessions | Access / Better Auth adapter | Better Auth-owned tables |
| Device-to-account membership | Access | Indexed provider membership by DID and device ID |
| Clients, grants and protocol state | Access / OAuth provider adapter | Provider stores, partly using namespaced JSON storage |
| Current placement | PDS fleet, exposed through Accounts | `pds_id` in the account row; static configuration supplies hosts |
| Transfer progress | PDS fleet workflow | Legacy operation store and newer versioned workflow/checkpoint tables |
| Public custody evidence | Identity | Import-time custody inventory; not a complete key lifecycle registry |
| Repository, blobs and repository key | Hosting PDS | Reference PDS-managed storage |
| Verified browser identity and sessions | Access / Better Auth adapter | Better Auth-owned tables |
| Device-to-account membership | Access | Indexed provider membership by DID and device ID |
| Clients, grants and protocol state | Access / OAuth provider adapter | Provider stores, partly using namespaced JSON storage |
| Current placement | PDS fleet, exposed through Accounts | `pds_id` in the account row; static configuration supplies hosts |
| Transfer progress | PDS fleet workflow | Legacy operation store and newer versioned workflow/checkpoint tables |
| Public custody evidence | Identity | Import-time custody inventory; not a complete key lifecycle registry |
| Repository, blobs and repository key | Hosting PDS | Reference PDS-managed storage |

The database boundary stores account authority, browser authentication, OAuth
state, mail and workflow journals in one selected database: `account-authority.sqlite`
Expand Down Expand Up @@ -410,6 +410,20 @@ cannot bypass guarded activation or ordinary-access restrictions. This differs
from the current fixture's post-transfer binding and does not change existing
signup activation semantics. Implementation and public qualification remain open.

The user accepted the [C4 client-managed contract](incoming-migration.md#c4-client-managed-migration-contract-accepted)
on 2026-11-11, replacing the former Entryway final-source/inventory certification
and global verification-to-activation write-barrier requirement. The client owns
record/blob transfer, checks its chosen transferred state and requests activation
when it chooses; concurrent/later source writes and unavailable blobs may be absent.
Counts, zero missing blobs and completion flags are diagnostics/intent, never
source ownership or independent completeness proof. Entryway still checks authorized
intent, canonical PLC endpoint/key/rotation custody/handle, expected placement,
saved-user binding, backend state and durable ownership on every pending activation
path. Uncertain writes retain isolation/drain recovery and idempotent journals.
Source deactivation follows confirmed destination activation as a client action.
This decision changes neither early cutover nor the access-JWT revocation gap;
credential lifecycle, public integration and runtime qualification remain pending.

Tools may implement an Entryway-specific public journey; no particular tool is
mandatory or assumed compatible. Arrival-code expiry does not release uncertain
operations or reverse published custody. No automatic destructive cleanup or
Expand Down
Loading
Loading