Skip to content
identity

identity

Who an account is: DID and handle syntax, resolution, the two-way handle check, and the onboarding and email decisions. Package @unset/domains-identity. The network port is ADR 0013, still Proposed (awaiting Alex).

Owns

Product rules for identity. The folder does not open a socket. Callers pass an IdentityNetwork (domains/identity/contract.ts): get(url, request) and txt(name). infrastructure/pds/identity-network.ts implements that type.

ModuleWhat it holds
domains/identity/index.tsPackage root. Re-exports the rows below.
domains/identity/syntax.tsparseDid, parseHandle, isHandleSyntax, and the branded Did and Handle types.
domains/identity/contract.tsIdentityNetwork and its outcome types.
domains/identity/account.tsAccountRepository (get, confirmAdult, acceptTerms, finishChat, blockUnderage) and UnderageBlockRecord.
domains/identity/did-doc.tsparseDidDoc. Not a package export. resolve-did.ts is the caller.
domains/identity/resolve-did.tscreateDidResolver, IdentityError.
domains/identity/resolve-handle.tsresolveHandle.
domains/identity/verify-handle.tscreateHandleVerifier, displayHandle. Trusted base in .github/CODEOWNERS (# trusted base (SE-6)).
domains/identity/in-flight.tsOne shared lookup per DID. Not a package export.
domains/identity/auth/age.tsparseBirthDate, ageInYears, latestCalendarDay.
domains/identity/auth/gates.tsemailGate, CACHED_RECHECK_CAP_MULTIPLE, cachedRecheckCapS, verifiedAfterRefresh, onboardingStep, requireOnboarded.
domains/identity/legal/versions.tsTERMS_VERSION, PRIVACY_VERSION.
domains/identity/sign-in-history.tsThe Sign-in history port SignInHistory (list, remove, remove up to), SignInId, parseSignInId, parseSignInIds, HISTORY_LIMIT (50), SIGN_IN_KEEP_DAYS (30). The rows are app.sign_in (migration 0038, ADR 0082).

parseDid accepts did:plc (24 base32 characters) or did:web plus a hostname isResolvableHostname accepts. It does not lowercase. parseHandle trims, drops one leading @, and lowercases. It returns null unless that result is a hostname isResolvableHostname accepts. isHandleSyntax is that hostname pattern before the disallowed-TLD list: the string must be printable ASCII and at most 253 characters, judged after lowercasing. It does not trim or drop @. A name such as alice.local passes isHandleSyntax and is still null from parseHandle. The lists and the spec cites are in syntax.ts.

resolveHandle tries a _atproto TXT record, then https://<handle>/.well-known/atproto-did. Statuses: found, not_found, unavailable (resolve-handle.ts). TXT is found when the did= values parseDid accepts are exactly one DID. Repeating that DID is still one DID. A record that does not start with did=, or whose remainder parseDid rejects, is ignored. Two different DIDs are a conflict: the status is unavailable and HTTPS is not asked. Otherwise a method that returns one DID wins, so a found TXT answer does not ask HTTPS. If neither method returns a DID, one method that could not tell makes the status unavailable, and two methods that found nothing make it not_found. A _atproto. name longer than 253 characters is not queried; that method counts as none.

Network failureRaised byAdapter (infrastructure/pds/identity-network.ts)Status when the other method found nothing
egress.dns_no_recordTXT: NXDOMAIN, NODATA or an empty answer (infrastructure/net-guard/src/dns.ts). Well-known host: NXDOMAIN or NODATA on both address families, or an empty answer (infrastructure/net-guard/src/resolve.ts, P2.01m). Any other error on either family is egress.dns_failed, not this code.txt returns no_record. get returns no_such_host. Both are none in resolve-handle.ts.not_found
egress.dns_failed, egress.dns_timeoutEither method.unavailable. txt maps every NetGuardError other than egress.dns_no_record to unavailable.unavailable
egress.connect, egress.tls, egress.timeoutThe HTTPS method.unavailableunavailable
A refusal (egress.private_address, egress.redirect, egress.too_large, and the other refusal codes in FAILURE)The HTTPS method. resolveTxt does not raise them.get returns refused, which fromWellKnown treats as none.not_found

A handle domain with no DNS record is egress.dns_no_record on both methods, so not_found. ADR 0013 decision 4 said that case was unavailable until P2.01m. P2.01m has landed, so that clause has expired. The ADR is still Proposed (awaiting Alex). The ADR file is not edited. An HTTPS status of 429 or 500 and above is unavailable from the response (fromWellKnown), not from a net-guard code.

createHandleVerifier returns verifyHandle and invalidateHandle. The claim is the first string in rawAlsoKnownAs that starts with at:// and whose remainder does not start with @, has no surrounding whitespace, and passes isHandleSyntax. Every later entry is ignored. parseHandle lowercases that remainder. When it returns null, the verdict is invalid and nothing is resolved. verifyHandle returns verified when the claim resolves back to that DID. displayHandle returns that handle, or the string handle.invalid. The other verdicts are invalid and unavailable (verify-handle.ts).

emailGate reads a cache the caller passes. It does not take a handle or an environment.

EmailCache and recheckSEmailGate
confirmed is not trueverify
checkedAt is nullrefresh
the check age is from 0 through recheckS secondspass
anything elserefresh

verifiedAfterRefresh(answer, cache, nowMs, recheckS) returns pass, verify, ended or unavailable.

EmailRefreshResult
confirmedpass
unconfirmedverify
endedended
transient, while withinCachedRecheckCap holdspass
transient, otherwiseunavailable

withinCachedRecheckCap holds when checkedAt is set and the cache age is from 0 through cachedRecheckCapS(recheckS) seconds. cachedRecheckCapS is recheckS times CACHED_RECHECK_CAP_MULTIPLE, and that constant is 4. A null checkedAt, or a checkedAt later than nowMs, is outside that range, so transient is unavailable. confirmed, unconfirmed and ended do not read the cache.

onboardingStep is the first unfinished step. A null account is age. done stays done only when termsVersion equals the current terms version; a terms mismatch returns terms. blocked_underage returns blocked.

requireOnboarded turns that step into a decision:

StepOutcome
donepass. privacyNotice is true when privacyVersion differs from the current privacy version.
termsterms
blockedblocked
age, chatwelcome

interfaces/web/src/lib/server/app-gate.ts turns the decision into a redirect. This folder does not.

parseBirthDate returns a calendar date or null. ageInYears counts full UTC years. interfaces/web/src/routes/welcome/age/+page.server.ts passes latestCalendarDay(new Date()) as today. Neither function stores the date.

May import

The Domains domain row, and the narrowing rules on that page.

Product files under domains/identity import only other files in that folder. domains/identity/package.json declares no dependencies.

Entry points

RolePath
Package export .domains/identity/index.ts
Package export ./syntaxdomains/identity/syntax.ts
Composition rootinterfaces/web/src/lib/server/compose.ts calls createDidResolver and createHandleVerifier, and reads TERMS_VERSION and PRIVACY_VERSION
Port implementationinfrastructure/pds/identity-network.ts
OAuth resolversinfrastructure/pds/oauth/identity-resolvers.ts imports parseDid, parseHandle, resolveHandle and IdentityError
Syntax-only callerinfrastructure/audit/append.ts imports parseDid from @unset/domains-identity/syntax

./syntax is the subpath in package.json exports. domains/identity/syntax-export.test.ts checks that it resolves to syntax.ts. There is no main.ts.

Re-exports from index.ts:

FromNames
account.tsAccountRepository, UnderageBlockRecord
auth/age.tsageInYears, parseBirthDate, latestCalendarDay, BirthDate
auth/gates.tsemailGate, cachedRecheckCapS, verifiedAfterRefresh, onboardingStep, requireOnboarded, and the types EmailCache, EmailGate, EmailRefresh, Onboarding, OnboardingAccount, OnboardingDecision, OnboardingStep, OnboardingVersions
contract.tsFetchRequest, FetchTarget, HttpOutcome, IdentityNetwork, TxtOutcome
did-doc.tsResolvedDid
legal/versions.tsPRIVACY_VERSION, TERMS_VERSION
resolve-did.tscreateDidResolver, IdentityError, Consistency, DidResolverOptions, IdentityErrorKind
resolve-handle.tsresolveHandle, HandleResolution
syntax.tsparseDid, parseHandle, isHandleSyntax, Did, Handle
verify-handle.tscreateHandleVerifier, displayHandle, HandleVerdict, HandleVerifierOptions

Data

No schema, role, table or event type. The resolver and the verifier each keep an in-memory map keyed by DID (resolve-did.ts, verify-handle.ts). invalidateHandle deletes one verifier entry. Nothing here writes Postgres.

Values the gates read, stored by the caller:

ShapeFieldsStored by
OnboardingAccountonboarding, termsVersion, privacyVersioninfrastructure/postgres/accountRepository.ts (the AccountRepository contract in account.ts) reads onboarding, terms_version, privacy_version from app.account
EmailCacheconfirmed, checkedAtopenApp (interfaces/web/src/lib/server/app-gate.ts) sets confirmed to session.emailConfirmed and checkedAt to session.emailCheckedAt, or null when the session has no check time. read (infrastructure/session/store.ts) selects email_confirmed and email_checked_at from app.session

app.account is created in infrastructure/postgres/migrations/0015_app_account.sql. It has age_confirmed_at and no birth-date column. TERMS_VERSION and PRIVACY_VERSION are the constants in legal/versions.ts. The comment in domains/identity/legal/versions.ts names the check legal.versions_exported against the version in apps/web/legal/terms.en.md and apps/web/legal/privacy.en.md.