@libid/contracts 0.17.0 → 0.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/README.md +108 -47
  2. package/dist/abis/bindErrors.d.ts +714 -0
  3. package/dist/abis/bindErrors.d.ts.map +1 -0
  4. package/dist/abis/bindErrors.js +955 -0
  5. package/dist/abis/bindErrors.js.map +1 -0
  6. package/dist/abis/ceremonyPayloads.d.ts +118 -0
  7. package/dist/abis/ceremonyPayloads.d.ts.map +1 -0
  8. package/dist/abis/ceremonyPayloads.js +154 -0
  9. package/dist/abis/ceremonyPayloads.js.map +1 -0
  10. package/dist/abis/ceremonyProofVerifier.d.ts +6 -6
  11. package/dist/abis/ceremonyProofVerifier.js +6 -6
  12. package/dist/abis/ceremonyProofVerifier.js.map +1 -1
  13. package/dist/abis/handleEscrow.d.ts +56 -16
  14. package/dist/abis/handleEscrow.d.ts.map +1 -1
  15. package/dist/abis/handleEscrow.js +71 -19
  16. package/dist/abis/handleEscrow.js.map +1 -1
  17. package/dist/abis/honkVerifierErrors.d.ts +54 -0
  18. package/dist/abis/honkVerifierErrors.d.ts.map +1 -0
  19. package/dist/abis/honkVerifierErrors.js +71 -0
  20. package/dist/abis/honkVerifierErrors.js.map +1 -0
  21. package/dist/abis/identityRegistry.d.ts +123 -157
  22. package/dist/abis/identityRegistry.d.ts.map +1 -1
  23. package/dist/abis/identityRegistry.js +150 -194
  24. package/dist/abis/identityRegistry.js.map +1 -1
  25. package/dist/abis/index.d.ts +3 -0
  26. package/dist/abis/index.d.ts.map +1 -1
  27. package/dist/abis/index.js +3 -0
  28. package/dist/abis/index.js.map +1 -1
  29. package/dist/calls/handleEscrow.d.ts +1 -0
  30. package/dist/calls/handleEscrow.d.ts.map +1 -1
  31. package/dist/calls/handleEscrow.js +7 -0
  32. package/dist/calls/handleEscrow.js.map +1 -1
  33. package/dist/calls/identityRegistry.d.ts +2 -1
  34. package/dist/calls/identityRegistry.d.ts.map +1 -1
  35. package/dist/calls/identityRegistry.js +9 -2
  36. package/dist/calls/identityRegistry.js.map +1 -1
  37. package/dist/ceremony/profiles.d.ts +38 -48
  38. package/dist/ceremony/profiles.d.ts.map +1 -1
  39. package/dist/ceremony/profiles.js +31 -36
  40. package/dist/ceremony/profiles.js.map +1 -1
  41. package/dist/identity/index.d.ts +1 -3
  42. package/dist/identity/index.d.ts.map +1 -1
  43. package/dist/identity/index.js +5 -11
  44. package/dist/identity/index.js.map +1 -1
  45. package/dist/identity/resolve.d.ts +6 -8
  46. package/dist/identity/resolve.d.ts.map +1 -1
  47. package/dist/identity/resolve.js +53 -86
  48. package/dist/identity/resolve.js.map +1 -1
  49. package/dist/index.d.ts +1 -0
  50. package/dist/index.d.ts.map +1 -1
  51. package/dist/index.js +3 -4
  52. package/dist/index.js.map +1 -1
  53. package/dist/payloads.d.ts +124 -0
  54. package/dist/payloads.d.ts.map +1 -0
  55. package/dist/payloads.js +59 -0
  56. package/dist/payloads.js.map +1 -0
  57. package/dist/platforms/handle.d.ts +11 -0
  58. package/dist/platforms/handle.d.ts.map +1 -0
  59. package/dist/platforms/handle.js +29 -0
  60. package/dist/platforms/handle.js.map +1 -0
  61. package/dist/platforms/id.d.ts +8 -0
  62. package/dist/platforms/id.d.ts.map +1 -0
  63. package/dist/platforms/id.js +21 -0
  64. package/dist/platforms/id.js.map +1 -0
  65. package/dist/platforms/index.d.ts +5 -0
  66. package/dist/platforms/index.d.ts.map +1 -0
  67. package/dist/platforms/index.js +8 -0
  68. package/dist/platforms/index.js.map +1 -0
  69. package/dist/platforms/node.d.ts +4 -0
  70. package/dist/platforms/node.d.ts.map +1 -0
  71. package/dist/platforms/node.js +36 -0
  72. package/dist/platforms/node.js.map +1 -0
  73. package/dist/platforms/platforms.d.ts +39 -0
  74. package/dist/platforms/platforms.d.ts.map +1 -0
  75. package/dist/platforms/platforms.js +90 -0
  76. package/dist/platforms/platforms.js.map +1 -0
  77. package/package.json +11 -3
  78. package/src/abis/bindErrors.ts +957 -0
  79. package/src/abis/ceremonyPayloads.ts +156 -0
  80. package/src/abis/ceremonyProofVerifier.ts +6 -6
  81. package/src/abis/handleEscrow.ts +71 -19
  82. package/src/abis/honkVerifierErrors.ts +73 -0
  83. package/src/abis/identityRegistry.ts +150 -194
  84. package/src/abis/index.ts +3 -0
  85. package/src/calls/handleEscrow.ts +12 -0
  86. package/src/calls/identityRegistry.ts +14 -2
  87. package/src/ceremony/profiles.ts +53 -65
  88. package/src/identity/index.ts +5 -11
  89. package/src/identity/resolve.ts +71 -118
  90. package/src/index.ts +3 -4
  91. package/src/payloads.ts +90 -0
  92. package/src/platforms/handle.ts +36 -0
  93. package/src/platforms/id.ts +26 -0
  94. package/src/platforms/index.ts +8 -0
  95. package/src/platforms/node.ts +41 -0
  96. package/src/platforms/platforms.ts +114 -0
  97. package/dist/identity/handle.d.ts +0 -22
  98. package/dist/identity/handle.d.ts.map +0 -1
  99. package/dist/identity/handle.js +0 -140
  100. package/dist/identity/handle.js.map +0 -1
  101. package/dist/identity/handleVectors.d.ts +0 -50
  102. package/dist/identity/handleVectors.d.ts.map +0 -1
  103. package/dist/identity/handleVectors.js +0 -89
  104. package/dist/identity/handleVectors.js.map +0 -1
  105. package/dist/identity/node.d.ts +0 -5
  106. package/dist/identity/node.d.ts.map +0 -1
  107. package/dist/identity/node.js +0 -19
  108. package/dist/identity/node.js.map +0 -1
  109. package/src/identity/handle.ts +0 -176
  110. package/src/identity/handleVectors.ts +0 -104
  111. package/src/identity/node.ts +0 -28
@@ -2,26 +2,19 @@
2
2
  // The source of truth is solidity/contracts/ceremony/profiles.json.
3
3
 
4
4
  /**
5
- * The single source of truth for the ceremony profiles. Solidity, Rust and
6
- * TypeScript constants are generated from this file by
7
- * scripts/regen-ceremony-profiles.py. The Platform Verifiers are hand
8
- * written and READ these constants; only the values live here.
5
+ * The ceremony profiles. scripts/regen-ceremony-profiles.py generates
6
+ * the Solidity, Rust and TypeScript constants from profiles.json, and
7
+ * the hand-written Platform Verifiers read them.
9
8
  *
10
- * THESE STRINGS ARE OURS, NOT THE SPECIFICATION'S. ceremony-common fixes no
11
- * literal of its own: platform-ceremonies REQ-PLAT-01 fixes the profile
12
- * NAMES, and every byte below is the profile author's choice. So this is a
13
- * cross-implementation agreement, and it is agreed here rather than three
14
- * times over.
9
+ * These literals are the one copy the verifiers, the browser that
10
+ * notarizes the sessions and the notary must reproduce byte for byte.
11
+ * A mismatch fails silently: a Consumer and a verifier keyed by
12
+ * different strings never meet, and a request line composed one byte
13
+ * differently is refused with no reason given.
15
14
  *
16
- * Three components must produce the same bytes: this repository's verifiers,
17
- * the browser that notarizes all four sessions, and the notary that signs
18
- * what it observed. A disagreement is silent -- a Consumer dispatching on one
19
- * string and a verifier registered under another simply never meet, and a
20
- * request line a prover composes one byte differently is an attestation
21
- * rejected with no error that says why.
22
- *
23
- * Changing a value here changes what a deployed verifier accepts. That is a
24
- * new ceremonyVersion, not an edit.
15
+ * Changing a value changes what a deployed verifier accepts. On a live
16
+ * deployment that is a new ceremonyVersion; a fresh deployment keeps its
17
+ * versions.
25
18
  */
26
19
 
27
20
  /** Which shape a platform's immutable identifier takes in its response. */
@@ -38,22 +31,22 @@ export interface Session {
38
31
 
39
32
  export interface TokenSession {
40
33
  readonly session: Session
41
- /** The header lines a Platform Verifier requires, each exactly once with
42
- * its value: `host` and `content-type`. Every other header is the
43
- * runtime's own, save the names `FORBIDDEN_REQUEST_HEADERS` lists.
44
- * `content-length` is absent: the HTTP client appends it. */
34
+ /** The header lines a Platform Verifier requires exactly once: `host`
35
+ * and `content-type`. Other headers pass unless
36
+ * `FORBIDDEN_REQUEST_HEADERS` names them. `content-length` is absent:
37
+ * the HTTP client writes it. */
45
38
  readonly requiredHeaders: readonly string[]
46
- /** The form fields the body carries, in the order the prover serializes
47
- * them. Every verifier holds the whole body to this list: exactly these
48
- * names in this order, each once with a nonempty value, nothing after
49
- * the last. GitHub's list is REQ-PLAT-61's; X's specification keeps its
50
- * decoded form on ASM-PROV-07, so the contract is stricter than the
51
- * specification there. */
39
+ /** The body's form fields in serialization order. Verifiers require
40
+ * exactly these names in this order, each once with a nonempty value,
41
+ * and nothing after the last. GitHub's list is REQ-PLAT-61's and X's
42
+ * is REQ-PLAT-63's. */
52
43
  readonly tokenFields: readonly string[]
53
44
  }
54
45
 
55
46
  export interface IdentitySession {
56
47
  readonly session: Session
48
+ /** The header lines a Platform Verifier requires exactly once: `host`. */
49
+ readonly requiredHeaders: readonly string[]
57
50
  readonly idField: string
58
51
  readonly idShape: IdShape
59
52
  readonly handleField: string
@@ -68,9 +61,9 @@ export interface Profile {
68
61
  }
69
62
 
70
63
  /**
71
- * Google's evidence is a signed token checked against Google's published
72
- * keys, so the profile notarizes nothing: no session, no attestation,
73
- * and no Notary Fee.
64
+ * Google's evidence is a token signed with Google's published keys, so
65
+ * the profile notarizes nothing: no session, no attestation and no
66
+ * Notary Fee.
74
67
  */
75
68
  export const GOOGLE: Profile = {
76
69
  platform: 'google',
@@ -103,6 +96,7 @@ export const X: Profile = {
103
96
  path: '/2/users/me',
104
97
  requestLine: 'GET /2/users/me ',
105
98
  },
99
+ requiredHeaders: ['host: api.x.com'],
106
100
  idField: 'id',
107
101
  idShape: 'jsonString',
108
102
  handleField: 'username',
@@ -111,9 +105,8 @@ export const X: Profile = {
111
105
 
112
106
  /**
113
107
  * The credential GitHub calls `client_secret` is sent and revealed, so
114
- * an attestation publishes it and nothing here is confidential. The two
115
- * sessions are served by DIFFERENT hosts -- which is why one pinned
116
- * authority per profile would be wrong.
108
+ * an attestation publishes it. The two sessions are served by different
109
+ * hosts, so each session pins its own authority.
117
110
  */
118
111
  export const GITHUB: Profile = {
119
112
  platform: 'github',
@@ -135,13 +128,14 @@ export const GITHUB: Profile = {
135
128
  path: '/user',
136
129
  requestLine: 'GET /user ',
137
130
  },
131
+ requiredHeaders: ['host: api.github.com'],
138
132
  idField: 'id',
139
133
  idShape: 'jsonInteger',
140
134
  handleField: 'login',
141
135
  },
142
136
  }
143
137
 
144
- /** The closed launch list. */
138
+ /** The launch profiles. */
145
139
  export const LAUNCH: readonly Profile[] = [GOOGLE, X, GITHUB]
146
140
 
147
141
  /** The launch profile for a platform name, or undefined. */
@@ -155,19 +149,17 @@ export function attestationCount(profile: Profile): number {
155
149
  }
156
150
 
157
151
  /**
158
- * Header names no notarized request may carry, compared by every
159
- * Platform Verifier with the name lowercased, its whitespace removed and
160
- * `_` read as `-`. Each changes what the platform does with the request
161
- * in a way no revealed byte shows: `authorization` which client it
162
- * authenticates, `content-encoding` and `transfer-encoding` which bytes
163
- * it parses, `cookie` which session it answers for, the three override
164
- * names which method it runs. The identity request is excepted from
165
- * `authorization` alone: its one such header, under any scheme, is what
166
- * REQ-COMMON-39 counts. On the token request the verifier further
167
- * requires each session's requiredHeaders, `host` and `content-type`,
168
- * reads `content-length`, and ignores every other header: one outside
169
- * both lists changes only what the platform answers, and a wrong answer
170
- * is a response the verifier cannot read.
152
+ * Header names no notarized request may carry, compared lowercased, with
153
+ * whitespace removed and `_` read as `-`. Each changes what the platform
154
+ * does in a way no revealed byte shows: `authorization` the client it
155
+ * authenticates, `content-encoding` and `transfer-encoding` the bytes it
156
+ * parses, `cookie` the session, the three override names the method. The
157
+ * identity request is excepted from `authorization` alone: its one such
158
+ * header, under any scheme, is what REQ-COMMON-39 counts. The verifier
159
+ * also requires each session's requiredHeaders once with their value,
160
+ * reads the token request's `content-length`, and ignores every other
161
+ * header: such a header changes only the response, which the verifier
162
+ * then cannot read.
171
163
  */
172
164
  export const FORBIDDEN_REQUEST_HEADERS: readonly string[] = [
173
165
  'authorization',
@@ -180,19 +172,16 @@ export const FORBIDDEN_REQUEST_HEADERS: readonly string[] = [
180
172
  ]
181
173
 
182
174
  // The seconds each profile fixes. A Platform Verifier reads them as
183
- // constants: they belong to the profile like its request lines, an upgrade
184
- // of the verifier keeps them, and a different value is a new
185
- // ceremonyVersion (REQ-PARAM-01). A browser that knows the version it ran
186
- // therefore knows the validity every chain enforces. `IdentityRegistry`
187
- // supersedes a binding only on a strictly newer `observedAt`, so an
188
- // allowance too generous lets a proof dated ahead hold a name until the
189
- // clock catches up.
190
-
191
- // The signed `exp` bounds validity, so the profile fixes no lifetime
192
- // and no attestation skew. The OIDC circuit exposes no `iat`, so the
193
- // observation is the token's `exp`: Google issues about an hour of
194
- // life, and the claim reads roughly an hour ahead of the moment it
195
- // describes.
175
+ // constants, so a different value is a new ceremonyVersion (REQ-PARAM-01)
176
+ // and a client that knows its version knows the validity every chain
177
+ // enforces. `IdentityRegistry` replaces a binding only on a strictly newer
178
+ // `observedAt`, so the future allowance bounds how long a proof dated ahead
179
+ // holds a name.
180
+
181
+ // The signed `exp` bounds validity, so the profile fixes no lifetime and
182
+ // no attestation skew. The OIDC circuit exposes no `iat`, so the
183
+ // observation is the token's `exp`, about an hour after Google issued
184
+ // it.
196
185
  /**
197
186
  * `google/v1`: how far ahead of Block Time the evidence time may run.
198
187
  * The verifier subtracts it, so every version of a platform reports
@@ -200,10 +189,9 @@ export const FORBIDDEN_REQUEST_HEADERS: readonly string[] = [
200
189
  */
201
190
  export const FUTURE_OBSERVATION_ALLOWANCE_SECONDS_GOOGLE = 7200
202
191
 
203
- // The token attestation's creation time is the evidence time. A
204
- // notary states wall-clock time as it observes it, so the observation
205
- // is never ahead: five minutes covers clock skew between the notary
206
- // and the chain.
192
+ // The token attestation's creation time is the evidence time. A notary
193
+ // states the wall-clock time it observes, so five minutes covers clock
194
+ // skew between the notary and the chain.
207
195
  /**
208
196
  * `x/v1`: maximum age of the token attestation.
209
197
  */
@@ -1,14 +1,8 @@
1
- /// The wallet-agnostic identity system, TypeScript half.
1
+ /// Identity helpers: handle normalization, node derivation, and resolvers over
2
+ /// the `IdentityRegistry` view calls.
2
3
  ///
3
- /// Handle normalization mirrors the on-chain normalizer byte for byte, and the
4
- /// resolvers wrap the `IdentityRegistry` view calls. Everything on-chain-shaped
5
- /// comes from the generated ABIs in `../abis`, so this layer and the contracts
6
- /// cannot drift apart silently.
7
- ///
8
- /// Calldata for the writes is generated too, in `../calls` — `unpublish` had a
9
- /// hand-written builder here until every write function got one.
4
+ /// Normalization applies the token check and the fold the circuits enforce;
5
+ /// the chain only folds A-Z. Calldata for the writes is in `../calls`.
10
6
 
11
- export * from './handle.js'
12
- export * from './handleVectors.js'
13
- export * from './node.js'
7
+ export * from '../platforms/index.js'
14
8
  export * from './resolve.js'
@@ -1,25 +1,19 @@
1
- /// Reading identities from the chain.
1
+ /// Reads identities from the `IdentityRegistry` through view calls.
2
2
  ///
3
- /// Everything here is a view call. Binding an identity needs a ceremony payload
4
- /// and a wallet; reading one needs neither, which is the point — any product
5
- /// can resolve a handle without touching the ceremony that bound it.
6
- ///
7
- /// The client and the contract address are arguments rather than imports. This
8
- /// package ships separately from the repository it currently lives in, so it
9
- /// carries no configuration of its own and reaches for nothing outside itself.
3
+ /// The caller passes the client and the contract address; the package carries
4
+ /// no network configuration.
10
5
 
11
- import { type Address, keccak256, type PublicClient, toHex, zeroAddress } from 'viem'
6
+ import { type Address, keccak256, type PublicClient, toHex, zeroAddress, zeroHash } from 'viem'
12
7
 
13
8
  import { identityRegistryAbi } from '../abis/identityRegistry.js'
14
- import type { Rules } from './handle.js'
9
+ import { HandleError, handleNode, PLATFORMS } from '../platforms/index.js'
15
10
 
16
- /// A platform key (`'x'`, `'github'`, ...), refusing at compile time a value
17
- /// typed as hex: an id passed where a key belongs would be hashed again into a
18
- /// platform nothing binds.
11
+ /// A platform key (`'x'`, `'github'`, ...). A value typed as hex fails to
12
+ /// compile: an id passed as a key would hash into a platform nothing binds.
19
13
  export type PlatformKey<K extends string> = K extends `0x${string}` ? never : K
20
14
 
21
- /// A platform id is `keccak256` of its platform key. The keys are generated
22
- /// from `handles.json`, so this and the contract agree by construction.
15
+ /// A platform id is `keccak256` of its platform key, as `CeremonyProfile`
16
+ /// derives it.
23
17
  export function platformId<K extends string>(platformKey: PlatformKey<K>): `0x${string}` {
24
18
  return keccak256(toHex(platformKey))
25
19
  }
@@ -30,12 +24,8 @@ export interface RegistryReader {
30
24
  address: Address
31
25
  }
32
26
 
33
- /// One view call.
34
- ///
35
- /// Routed through a narrow cast for one reason:
36
- /// viem's `PublicClient`, without its chain type parameters, types
37
- /// `authorizationList` as required even for a read. The alternative is to
38
- /// spread that noise across every call site here.
27
+ /// One view call. The cast is there because viem's `PublicClient`, without its
28
+ /// chain type parameters, types `authorizationList` as required even for a read.
39
29
  function read<T>(
40
30
  reader: RegistryReader,
41
31
  functionName: string,
@@ -54,116 +44,88 @@ function read<T>(
54
44
  })
55
45
  }
56
46
 
57
- /// The platform's normalization rules as configured on chain now
58
- /// (`IdentityRegistry.rulesOf`).
59
- export async function rulesOf(reader: RegistryReader, platformId: `0x${string}`): Promise<Rules> {
60
- const rules = await read<Rules>(reader, 'rulesOf', [platformId])
61
- return {
62
- maxLength: Number(rules.maxLength),
63
- stripLeadingAt: rules.stripLeadingAt,
64
- isEmail: rules.isEmail,
65
- allowUnderscore: rules.allowUnderscore,
66
- allowHyphen: rules.allowHyphen,
67
- }
68
- }
69
-
70
- /// The holder that proved this id, or `null`.
47
+ /// The holder that proved this id node (`idNode(platformKey, id)`), or `null`.
71
48
  export async function resolveId(
72
49
  reader: RegistryReader,
73
- platformId: `0x${string}`,
74
- id: string,
75
- ): Promise<Address | null> {
76
- const holder = await read<Address>(reader, 'resolveId', [platformId, id])
77
- return holder === zeroAddress ? null : holder
78
- }
79
-
80
- /// The holder that last proved this handle, or `null`.
81
- ///
82
- /// The handle is normalized on chain before it is looked up, so a caller may
83
- /// pass what was typed — including something that is not a handle at all.
84
- /// The contract is total in the handle: a string the platform's rules refuse
85
- /// answers the zero address, which is the same answer as a handle nobody has
86
- /// proved, and the one a search box wants.
87
- ///
88
- /// A revert propagates. `UnknownPlatform` in particular means the platform is
89
- /// not configured, and answering "unbound" would bury a deployment mistake
90
- /// under a plausible result.
91
- export async function resolveHandle(
92
- reader: RegistryReader,
93
- platformId: `0x${string}`,
94
- handle: string,
50
+ idNode: `0x${string}`,
95
51
  ): Promise<Address | null> {
96
- const holder = await read<Address>(reader, 'resolveHandle', [platformId, handle])
52
+ const holder = await read<Address>(reader, 'resolveId', [idNode])
97
53
  return holder === zeroAddress ? null : holder
98
54
  }
99
55
 
100
- /// The handle to show for a holder, or `null`.
101
- ///
102
- /// Forward-checked on chain: empty once the stored handle resolves somewhere
103
- /// else. ENS asks integrators to perform that check themselves and warns that
104
- /// skipping it displays an ENS primary name that no longer resolves back; here
105
- /// it cannot be skipped, because the contract does it.
106
- export async function publishedHandleOf(
107
- reader: RegistryReader,
108
- holder: Address,
109
- platformId: `0x${string}`,
110
- ): Promise<string | null> {
111
- const handle = await read<string>(reader, 'publishedHandleOf', [holder, platformId])
112
- return handle.length === 0 ? null : handle
113
- }
56
+ /// The generated platforms, keyed by platform id.
57
+ const PLATFORM_BY_ID = new Map(PLATFORMS.map((p) => [platformId(p.key), p]))
114
58
 
115
59
  export interface HandleAndIdResolution {
116
60
  /// The handle's holder, or `null`.
117
61
  holder: Address | null
118
- /// True only when the id resolves to that same holder.
119
- ///
120
- /// False means the caller's `(handle, id)` pair comes from two moments:
121
- /// somebody proved the handle after the caller learned who held it. That is
122
- /// staleness, not corruption.
62
+ /// True only when the id node is the account that last proved the handle.
63
+ /// False when another account proved it since, even one in the same wallet.
123
64
  idAgrees: boolean
124
65
  }
125
66
 
126
- /// Resolve a handle and report whether an id still agrees with it.
127
- ///
128
- /// **Read this before signing, and do not let it block a transfer.** A handle
129
- /// that will not route is not a handle: sending to a handle means sending to
130
- /// whoever proved it last, which is what the handle now means. What the flag is
131
- /// for is telling whoever is paying that the identity they think they are
132
- /// paying is not the one that has the handle today — a decision they can only
133
- /// make beforehand.
134
- ///
135
- /// Both halves are needed. A handle on its own has nothing to disagree with.
136
- ///
137
- /// A handle the platform's rules reject resolves to `{holder: null, idAgrees:
138
- /// false}`, the same as one nobody has proved — see `resolveHandle`.
67
+ /// Resolve a handle and report whether an id node still agrees with it.
68
+ /// Read it before signing to warn the payer; do not let it block a transfer.
69
+ /// Only the handle's node is sent. Text no circuit hashes is sent as the zero
70
+ /// node and resolves to `{holder: null, idAgrees: false}`. Reverts such as
71
+ /// `UnknownPlatform` propagate; a platform missing from this package's table
72
+ /// throws.
139
73
  export async function resolveHandleAndId(
140
74
  reader: RegistryReader,
141
- platformId: `0x${string}`,
75
+ id: `0x${string}`,
142
76
  handle: string,
143
- id: string,
77
+ idNode: `0x${string}`,
144
78
  ): Promise<HandleAndIdResolution> {
145
- const [holder, idAgrees] = await read<[Address, boolean]>(reader, 'resolveHandleAndId', [
146
- platformId,
147
- handle,
79
+ const keys = PLATFORM_BY_ID.get(id.toLowerCase() as `0x${string}`)
80
+ let node: `0x${string}` = zeroHash
81
+ if (keys !== undefined) {
82
+ try {
83
+ node = handleNode(keys.key, handle)
84
+ } catch (e) {
85
+ if (!(e instanceof HandleError)) throw e
86
+ }
87
+ }
88
+ // The chain goes first, so a platform it does not know reverts UnknownPlatform there.
89
+ const [holder, idAgrees] = await read<[Address, boolean]>(reader, 'resolveHandleNodeAndId', [
148
90
  id,
91
+ node,
92
+ idNode,
149
93
  ])
150
-
94
+ if (keys === undefined) throw new Error(`platform ${id} is not in this package's handle table`)
151
95
  return { holder: holder === zeroAddress ? null : holder, idAgrees }
152
96
  }
153
97
 
98
+ /// The holder that last proved this handle, or `null`. Only the handle's node
99
+ /// is sent; text no circuit hashes also answers `null`. Reverts such as
100
+ /// `UnknownPlatform` propagate.
101
+ export async function resolveHandle(
102
+ reader: RegistryReader,
103
+ platformId: `0x${string}`,
104
+ handle: string,
105
+ ): Promise<Address | null> {
106
+ return (await resolveHandleAndId(reader, platformId, handle, zeroHash)).holder
107
+ }
108
+
109
+ /// The handle to show for a holder, or `null`. Forward-checked on chain:
110
+ /// empty once the stored handle resolves somewhere else.
111
+ export async function publishedHandleOf(
112
+ reader: RegistryReader,
113
+ holder: Address,
114
+ platformId: `0x${string}`,
115
+ ): Promise<string | null> {
116
+ const handle = await read<string>(reader, 'publishedHandleOf', [holder, platformId])
117
+ return handle.length === 0 ? null : handle
118
+ }
119
+
154
120
  /// One identity a holder proved, as the holder's list reports it.
155
121
  export interface Identity {
156
122
  /// The platform the identity is on, as `platformId` derives it.
157
123
  platformId: `0x${string}`
158
- /// The id, byte for byte as the platform issued it.
159
- id: string
160
- /// The handle this identity proved most recently, as normalized on chain.
161
- handle: string
124
+ /// The node of the id.
125
+ idNode: `0x${string}`
126
+ /// The node of the handle this identity proved most recently.
127
+ handleNode: `0x${string}`
162
128
  /// True while the handle node still points back at this identity.
163
- ///
164
- /// False once another identity proves the same handle: the string stays as
165
- /// the last thing this identity was known as, and the flag says not to route
166
- /// by it.
167
129
  handleCurrent: boolean
168
130
  }
169
131
 
@@ -172,17 +134,8 @@ export async function identityCount(reader: RegistryReader, holder: Address): Pr
172
134
  return read<bigint>(reader, 'identityCount', [holder])
173
135
  }
174
136
 
175
- /// A page of a holder's identities, on every platform together:
176
- /// the indices `[from, from + limit)` of its list, counted from zero and
177
- /// clipped to the list. A `from` past the end answers an empty page. A reader
178
- /// that wants one platform filters a page by `platformId`.
179
- ///
180
- /// Order is arbitrary and changes when an identity leaves the list, so two
181
- /// pages read across a removal may overlap or skip. A reader that needs every
182
- /// identity reads `identityCount` and the pages against one block.
183
- ///
184
- /// A list is as long as its holder made it, and a call's gas is not. A caller
185
- /// enumerating a holder it did not choose keeps `limit` small and pages.
137
+ /// The holder's identities at indices `[from, from + limit)`, clipped to the list.
138
+ /// Order is arbitrary and changes on removal: read every page against one block.
186
139
  export async function identitiesOf(
187
140
  reader: RegistryReader,
188
141
  holder: Address,
@@ -190,10 +143,10 @@ export async function identitiesOf(
190
143
  limit: bigint,
191
144
  ): Promise<Identity[]> {
192
145
  const page = await read<readonly Identity[]>(reader, 'identitiesOf', [holder, from, limit])
193
- return page.map(({ platformId, id, handle, handleCurrent }) => ({
146
+ return page.map(({ platformId, idNode, handleNode, handleCurrent }) => ({
194
147
  platformId,
195
- id,
196
- handle,
148
+ idNode,
149
+ handleNode,
197
150
  handleCurrent,
198
151
  }))
199
152
  }
package/src/index.ts CHANGED
@@ -1,10 +1,9 @@
1
- /// @libid/contracts — typed viem-ready ABIs for every contract, a call builder
2
- /// for every state-changing function, and the identity helper layer. Subpath
3
- /// imports work too: `@libid/contracts/abis`, `@libid/contracts/calls`,
4
- /// `@libid/contracts/identity` and `@libid/contracts/ceremony`.
1
+ /// @libid/contracts: viem-ready ABIs, call builders, identity helpers and
2
+ /// `bind` payload encoders. Subpaths: `/abis`, `/calls`, `/identity`, `/ceremony`.
5
3
 
6
4
  export * from './abis/index.js'
7
5
  export type { Call } from './call.js'
8
6
  export * as calls from './calls/index.js'
9
7
  export * from './ceremony/index.js'
10
8
  export * from './identity/index.js'
9
+ export * from './payloads.js'
@@ -0,0 +1,90 @@
1
+ /// The payloads `IdentityRegistry.bind` carries to a Platform Verifier,
2
+ /// encoded with the tuple types `ceremonyPayloadsAbi` carries, no selector.
3
+
4
+ import {
5
+ type AbiParameterToPrimitiveType,
6
+ decodeAbiParameters,
7
+ encodeAbiParameters,
8
+ type Hex,
9
+ hexToBigInt,
10
+ hexToBytes,
11
+ numberToHex,
12
+ sha256,
13
+ } from 'viem'
14
+
15
+ import { ceremonyPayloadsAbi } from './abis/ceremonyPayloads.js'
16
+
17
+ type PayloadFunction = Extract<(typeof ceremonyPayloadsAbi)[number], { type: 'function' }>
18
+ type PayloadName = PayloadFunction['name']
19
+ type Inputs<N extends PayloadName> = Extract<PayloadFunction, { name: N }>['inputs']
20
+
21
+ function inputs<N extends PayloadName>(name: N): Inputs<N> {
22
+ const item = ceremonyPayloadsAbi.find((entry) => entry.type === 'function' && entry.name === name)
23
+ if (!item) throw new Error(`ceremonyPayloadsAbi has no ${name}`)
24
+ return item.inputs as Inputs<N>
25
+ }
26
+
27
+ const TLS_NOTARY_PROOF = inputs('tlsNotaryProof')
28
+ const GOOGLE_PROOF = inputs('googleProof')
29
+
30
+ /// `TlsNotaryVerifierBase.TlsNotaryProof`: the `x/v1` and `github/v1` payload.
31
+ export type TlsNotaryProof = AbiParameterToPrimitiveType<(typeof TLS_NOTARY_PROOF)[0]>
32
+
33
+ /// `GooglePlatformVerifier.GoogleProof`: the `google/v1` payload.
34
+ export type GoogleProof = AbiParameterToPrimitiveType<(typeof GOOGLE_PROOF)[0]>
35
+
36
+ /// The `x/v1` or `github/v1` payload, as the verifier decodes it.
37
+ export function encodeTlsNotaryProof(payload: TlsNotaryProof): Hex {
38
+ return encodeAbiParameters(TLS_NOTARY_PROOF, [payload])
39
+ }
40
+
41
+ /// A TLSNotary payload back into its fields. Throws on bytes that are not one.
42
+ export function decodeTlsNotaryProof(data: Hex): TlsNotaryProof {
43
+ return decodeAbiParameters(TLS_NOTARY_PROOF, data)[0]
44
+ }
45
+
46
+ /// The `google/v1` payload, as the verifier decodes it.
47
+ export function encodeGoogleProof(payload: GoogleProof): Hex {
48
+ return encodeAbiParameters(GOOGLE_PROOF, [payload])
49
+ }
50
+
51
+ /// A Google payload back into its fields. Throws on bytes that are not one.
52
+ export function decodeGoogleProof(data: Hex): GoogleProof {
53
+ return decodeAbiParameters(GOOGLE_PROOF, data)[0]
54
+ }
55
+
56
+ /// The `google/v1` payload fields the verifier builds its public inputs from.
57
+ export type GoogleProofFields = Pick<GoogleProof, 'idNode' | 'handleNode' | 'exp' | 'modulus'>
58
+
59
+ /// The oidc-google public input that disagrees with the payload: the verifier
60
+ /// would fail the proof, so a client checks before sending.
61
+ export class GooglePublicInputMismatch extends Error {
62
+ constructor(readonly field: 'count' | 'digest' | 'audience') {
63
+ super(
64
+ `the proof's ${field} public input${field === 'count' ? 's do' : ' does'} not match the payload`,
65
+ )
66
+ this.name = 'GooglePublicInputMismatch'
67
+ }
68
+ }
69
+
70
+ /// The payload fields from the prover's 57 oidc-google public inputs
71
+ /// (REQ-PLAT-16B), after checking the digest the token's `nonce` carried and
72
+ /// the audience against what the verifier builds them from.
73
+ export function googleProofFields(
74
+ publicInputs: readonly Hex[],
75
+ expected: { digest: Hex; clientIdentifier: Hex },
76
+ ): GoogleProofFields {
77
+ if (publicInputs.length !== 57) throw new GooglePublicInputMismatch('count')
78
+ const field = (i: number) => hexToBigInt(publicInputs[i] as Hex)
79
+ const node = (i: number) => numberToHex((field(i) << 128n) | field(i + 1), { size: 32 })
80
+ const digest = hexToBytes(expected.digest)
81
+ if (digest.some((b, i) => field(i) !== BigInt(b))) throw new GooglePublicInputMismatch('digest')
82
+ if (node(32) !== sha256(expected.clientIdentifier))
83
+ throw new GooglePublicInputMismatch('audience')
84
+ return {
85
+ idNode: node(34),
86
+ handleNode: node(36),
87
+ exp: field(38),
88
+ modulus: publicInputs.slice(39, 57) as unknown as GoogleProof['modulus'],
89
+ }
90
+ }
@@ -0,0 +1,36 @@
1
+ /// Turns a typed handle into the form the identity circuits hash into a node.
2
+ /// Mirrors the circuits and Rust; all run the `handles.json` vectors.
3
+
4
+ import { HandleError, PLATFORM_GITHUB, PLATFORM_GOOGLE, PLATFORM_X, platform } from './platforms.js'
5
+
6
+ /// What one platform's circuit takes, generated from the circuits' `platforms.json`.
7
+ export interface Rules {
8
+ /** Bytes the circuit's buffer holds. */
9
+ maxLength: number
10
+ }
11
+
12
+ export const RULES_X: Rules = PLATFORM_X.rules
13
+ export const RULES_GITHUB: Rules = PLATFORM_GITHUB.rules
14
+ export const RULES_GOOGLE: Rules = PLATFORM_GOOGLE.rules
15
+
16
+ /// The rules for a platform key from the generated table.
17
+ export function rulesFor(platformKey: string): Rules | null {
18
+ return platform(platformKey)?.rules ?? null
19
+ }
20
+
21
+ /// A byte of a JSON string as sent: printable ASCII, not `"` or `\`.
22
+ export function isStringByte(b: number): boolean {
23
+ return b >= 0x20 && b <= 0x7e && b !== 0x22 && b !== 0x5c
24
+ }
25
+
26
+ /// The handle with A-Z folded. Throws a `HandleError` unless it is one JSON
27
+ /// string as a platform sends it, no longer than the circuit's buffer.
28
+ export function normalize(raw: string, rules: Rules): string {
29
+ // Bytes, not code units: the circuits measure and refuse bytes.
30
+ const input = new TextEncoder().encode(raw)
31
+ if (input.length === 0) throw new HandleError('Empty')
32
+ if (input.length > rules.maxLength) throw new HandleError('TooLong')
33
+ if (!input.every(isStringByte)) throw new HandleError('BadCharacter')
34
+ // ASCII alone, so this folds A-Z and nothing else.
35
+ return raw.toLowerCase()
36
+ }
@@ -0,0 +1,26 @@
1
+ /// The id check the identity circuits apply: an id is hashed exactly as the
2
+ /// platform sent it, so it is checked and never normalized.
3
+
4
+ import { isStringByte } from './handle.js'
5
+ import { IdError, platform } from './platforms.js'
6
+
7
+ /// What a platform allows in an id, as the generated table states it.
8
+ export interface IdRules {
9
+ /** Bytes the circuit's buffer holds. */
10
+ maxLength: number
11
+ /** True: ASCII digits. False: printable ASCII without a quote or backslash. */
12
+ decimal: boolean
13
+ }
14
+
15
+ /// Accept an id exactly as given, or throw an `IdError` saying why no circuit would hash it.
16
+ export function checkId(platformKey: string, id: string): void {
17
+ const rules = platform(platformKey)?.idRules
18
+ if (rules === undefined) throw new Error(`unknown platform ${JSON.stringify(platformKey)}`)
19
+ const bytes = new TextEncoder().encode(id)
20
+ if (bytes.length === 0) throw new IdError('Empty')
21
+ if (bytes.length > rules.maxLength) throw new IdError('TooLong')
22
+ for (const b of bytes) {
23
+ const ok = rules.decimal ? b >= 0x30 && b <= 0x39 : isStringByte(b)
24
+ if (!ok) throw new IdError('BadCharacter')
25
+ }
26
+ }