@libid/contracts 0.16.0 → 0.18.0

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 (106) 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 -2
  42. package/dist/identity/index.d.ts.map +1 -1
  43. package/dist/identity/index.js +5 -10
  44. package/dist/identity/index.js.map +1 -1
  45. package/dist/identity/node.d.ts +3 -3
  46. package/dist/identity/node.d.ts.map +1 -1
  47. package/dist/identity/node.js +25 -16
  48. package/dist/identity/node.js.map +1 -1
  49. package/dist/identity/resolve.d.ts +6 -8
  50. package/dist/identity/resolve.d.ts.map +1 -1
  51. package/dist/identity/resolve.js +54 -86
  52. package/dist/identity/resolve.js.map +1 -1
  53. package/dist/index.d.ts +1 -0
  54. package/dist/index.d.ts.map +1 -1
  55. package/dist/index.js +3 -4
  56. package/dist/index.js.map +1 -1
  57. package/dist/payloads.d.ts +124 -0
  58. package/dist/payloads.d.ts.map +1 -0
  59. package/dist/payloads.js +59 -0
  60. package/dist/payloads.js.map +1 -0
  61. package/dist/platforms/handle.d.ts +11 -0
  62. package/dist/platforms/handle.d.ts.map +1 -0
  63. package/dist/platforms/handle.js +29 -0
  64. package/dist/platforms/handle.js.map +1 -0
  65. package/dist/platforms/id.d.ts +8 -0
  66. package/dist/platforms/id.d.ts.map +1 -0
  67. package/dist/platforms/id.js +21 -0
  68. package/dist/platforms/id.js.map +1 -0
  69. package/dist/platforms/index.d.ts +4 -0
  70. package/dist/platforms/index.d.ts.map +1 -0
  71. package/dist/platforms/index.js +7 -0
  72. package/dist/platforms/index.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 +8 -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 -10
  89. package/src/identity/node.ts +25 -21
  90. package/src/identity/resolve.ts +72 -118
  91. package/src/index.ts +3 -4
  92. package/src/payloads.ts +90 -0
  93. package/src/platforms/handle.ts +36 -0
  94. package/src/platforms/id.ts +26 -0
  95. package/src/platforms/index.ts +7 -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/src/identity/handle.ts +0 -176
  106. package/src/identity/handleVectors.ts +0 -104
@@ -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,9 @@
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'
7
+ export * from '../platforms/index.js'
13
8
  export * from './node.js'
14
9
  export * from './resolve.js'
@@ -1,28 +1,32 @@
1
- /// Handle hashes and nodes, mirroring `IdentityRegistry.handleHashOf` and
2
- /// `handleNodeOfHash`, computed locally so the handle text never reaches an
3
- /// RPC. `HandleEscrow.deposit` takes the hash; `handleBinding` and the
4
- /// escrow's reads take the node.
1
+ /// The keys a binding is stored under, `SHA256(tag || value)`, computed
2
+ /// locally so the handle or id never reaches an RPC.
5
3
 
6
- import { encodeAbiParameters, type Hex, keccak256, toHex } from 'viem'
4
+ import { concat, type Hex, sha256, toHex } from 'viem'
7
5
 
8
- import { normalize, type Rules } from './handle.js'
6
+ import { checkId, normalize, type Platform, platform } from '../platforms/index.js'
9
7
 
10
- const HANDLE_NODE_V1: Hex = keccak256(toHex('libid.identity.handle-node.v1'))
8
+ function keysOf(platformKey: string): Platform {
9
+ const keys = platform(platformKey)
10
+ if (keys === undefined) throw new Error(`unknown platform ${JSON.stringify(platformKey)}`)
11
+ return keys
12
+ }
13
+
14
+ /// The node a typed handle is bound under: normalized, then hashed under
15
+ /// its handle tag. Throws `HandleError` for text no binding can have.
16
+ export function handleNode(platformKey: string, raw: string): Hex {
17
+ const keys = keysOf(platformKey)
18
+ return sha256(concat([toHex(keys.handleTag), toHex(normalize(raw, keys.rules))]))
19
+ }
11
20
 
12
- /// `keccak256` of `raw` normalized under `rules` (from `rulesOf`, or
13
- /// `rulesFor` offline). Throws `HandleError` for text the rules refuse.
14
- export function handleHash(raw: string, rules: Rules): Hex {
15
- return keccak256(toHex(normalize(raw, rules)))
21
+ /// The node `depositToHandle` and the registry's `handleNodeOf` derive from
22
+ /// `text`: A-Z folded, nothing checked, so text no circuit hashes has one too.
23
+ export function foldedHandleNode(platformKey: string, text: string): Hex {
24
+ const bytes = new TextEncoder().encode(text).map((b) => (b >= 0x41 && b <= 0x5a ? b + 0x20 : b))
25
+ return sha256(concat([toHex(keysOf(platformKey).handleTag), toHex(bytes)]))
16
26
  }
17
27
 
18
- /// The node a handle hash sits on, on the platform `platformId` names
19
- /// (`platformId(PLATFORM_X_KEY)`), as `IdentityRegistry.handleNodeOfHash` derives
20
- /// it.
21
- export function handleNode(platformId: Hex, hash: Hex): Hex {
22
- return keccak256(
23
- encodeAbiParameters(
24
- [{ type: 'bytes32' }, { type: 'bytes32' }, { type: 'bytes32' }],
25
- [HANDLE_NODE_V1, platformId, hash],
26
- ),
27
- )
28
+ /// The node an id is bound under: the id as given, under its user-id tag.
29
+ export function idNode(platformKey: string, id: string): Hex {
30
+ checkId(platformKey, id)
31
+ return sha256(concat([toHex(keysOf(platformKey).userIdTag), toHex(id)]))
28
32
  }
@@ -1,25 +1,20 @@
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, PLATFORMS } from '../platforms/index.js'
10
+ import { handleNode } from './node.js'
15
11
 
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.
12
+ /// A platform key (`'x'`, `'github'`, ...). A value typed as hex fails to
13
+ /// compile: an id passed as a key would hash into a platform nothing binds.
19
14
  export type PlatformKey<K extends string> = K extends `0x${string}` ? never : K
20
15
 
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.
16
+ /// A platform id is `keccak256` of its platform key, as `CeremonyProfile`
17
+ /// derives it.
23
18
  export function platformId<K extends string>(platformKey: PlatformKey<K>): `0x${string}` {
24
19
  return keccak256(toHex(platformKey))
25
20
  }
@@ -30,12 +25,8 @@ export interface RegistryReader {
30
25
  address: Address
31
26
  }
32
27
 
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.
28
+ /// One view call. The cast is there because viem's `PublicClient`, without its
29
+ /// chain type parameters, types `authorizationList` as required even for a read.
39
30
  function read<T>(
40
31
  reader: RegistryReader,
41
32
  functionName: string,
@@ -54,116 +45,88 @@ function read<T>(
54
45
  })
55
46
  }
56
47
 
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`.
48
+ /// The holder that proved this id node (`idNode(platformKey, id)`), or `null`.
71
49
  export async function resolveId(
72
50
  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,
51
+ idNode: `0x${string}`,
95
52
  ): Promise<Address | null> {
96
- const holder = await read<Address>(reader, 'resolveHandle', [platformId, handle])
53
+ const holder = await read<Address>(reader, 'resolveId', [idNode])
97
54
  return holder === zeroAddress ? null : holder
98
55
  }
99
56
 
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
- }
57
+ /// The generated platforms, keyed by platform id.
58
+ const PLATFORM_BY_ID = new Map(PLATFORMS.map((p) => [platformId(p.key), p]))
114
59
 
115
60
  export interface HandleAndIdResolution {
116
61
  /// The handle's holder, or `null`.
117
62
  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.
63
+ /// True only when the id node is the account that last proved the handle.
64
+ /// False when another account proved it since, even one in the same wallet.
123
65
  idAgrees: boolean
124
66
  }
125
67
 
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`.
68
+ /// Resolve a handle and report whether an id node still agrees with it.
69
+ /// Read it before signing to warn the payer; do not let it block a transfer.
70
+ /// Only the handle's node is sent. Text no circuit hashes is sent as the zero
71
+ /// node and resolves to `{holder: null, idAgrees: false}`. Reverts such as
72
+ /// `UnknownPlatform` propagate; a platform missing from this package's table
73
+ /// throws.
139
74
  export async function resolveHandleAndId(
140
75
  reader: RegistryReader,
141
- platformId: `0x${string}`,
76
+ id: `0x${string}`,
142
77
  handle: string,
143
- id: string,
78
+ idNode: `0x${string}`,
144
79
  ): Promise<HandleAndIdResolution> {
145
- const [holder, idAgrees] = await read<[Address, boolean]>(reader, 'resolveHandleAndId', [
146
- platformId,
147
- handle,
80
+ const keys = PLATFORM_BY_ID.get(id.toLowerCase() as `0x${string}`)
81
+ let node: `0x${string}` = zeroHash
82
+ if (keys !== undefined) {
83
+ try {
84
+ node = handleNode(keys.key, handle)
85
+ } catch (e) {
86
+ if (!(e instanceof HandleError)) throw e
87
+ }
88
+ }
89
+ // The chain goes first, so a platform it does not know reverts UnknownPlatform there.
90
+ const [holder, idAgrees] = await read<[Address, boolean]>(reader, 'resolveHandleNodeAndId', [
148
91
  id,
92
+ node,
93
+ idNode,
149
94
  ])
150
-
95
+ if (keys === undefined) throw new Error(`platform ${id} is not in this package's handle table`)
151
96
  return { holder: holder === zeroAddress ? null : holder, idAgrees }
152
97
  }
153
98
 
99
+ /// The holder that last proved this handle, or `null`. Only the handle's node
100
+ /// is sent; text no circuit hashes also answers `null`. Reverts such as
101
+ /// `UnknownPlatform` propagate.
102
+ export async function resolveHandle(
103
+ reader: RegistryReader,
104
+ platformId: `0x${string}`,
105
+ handle: string,
106
+ ): Promise<Address | null> {
107
+ return (await resolveHandleAndId(reader, platformId, handle, zeroHash)).holder
108
+ }
109
+
110
+ /// The handle to show for a holder, or `null`. Forward-checked on chain:
111
+ /// empty once the stored handle resolves somewhere else.
112
+ export async function publishedHandleOf(
113
+ reader: RegistryReader,
114
+ holder: Address,
115
+ platformId: `0x${string}`,
116
+ ): Promise<string | null> {
117
+ const handle = await read<string>(reader, 'publishedHandleOf', [holder, platformId])
118
+ return handle.length === 0 ? null : handle
119
+ }
120
+
154
121
  /// One identity a holder proved, as the holder's list reports it.
155
122
  export interface Identity {
156
123
  /// The platform the identity is on, as `platformId` derives it.
157
124
  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
125
+ /// The node of the id.
126
+ idNode: `0x${string}`
127
+ /// The node of the handle this identity proved most recently.
128
+ handleNode: `0x${string}`
162
129
  /// 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
130
  handleCurrent: boolean
168
131
  }
169
132
 
@@ -172,17 +135,8 @@ export async function identityCount(reader: RegistryReader, holder: Address): Pr
172
135
  return read<bigint>(reader, 'identityCount', [holder])
173
136
  }
174
137
 
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.
138
+ /// The holder's identities at indices `[from, from + limit)`, clipped to the list.
139
+ /// Order is arbitrary and changes on removal: read every page against one block.
186
140
  export async function identitiesOf(
187
141
  reader: RegistryReader,
188
142
  holder: Address,
@@ -190,10 +144,10 @@ export async function identitiesOf(
190
144
  limit: bigint,
191
145
  ): Promise<Identity[]> {
192
146
  const page = await read<readonly Identity[]>(reader, 'identitiesOf', [holder, from, limit])
193
- return page.map(({ platformId, id, handle, handleCurrent }) => ({
147
+ return page.map(({ platformId, idNode, handleNode, handleCurrent }) => ({
194
148
  platformId,
195
- id,
196
- handle,
149
+ idNode,
150
+ handleNode,
197
151
  handleCurrent,
198
152
  }))
199
153
  }
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
+ }