@trustlayer-foundation/aria-sdk 0.0.0-stage → 1.0.0

package/API.md

@@ -0,0 +1,207 @@
+# ARIA SDK 1.0 — API contract
+
+Status: implemented, version 1.0.0: inspection, trust, credential verification,
+exact-instance status and the trust interface ARIA AP works through.
+
+This package verifies credentials and their status. Requests, admission, operations and
+receipts are **ARIA AP**, the separate package in [`../aria-ap-ts`](../aria-ap-ts/API.md),
+which builds on this one. A service that only checks credentials needs only this package.
+
+## Results, kept apart
+
+| Result | Says | Does not say |
+|---|---|---|
+| `Inspection` (`inspectCredential`) | The fields a document carries | Anything verified: `verified` is always `false` |
+| `VerifiedCredential` (`verifyCredential`) | This exact document conforms to its `spec_version`, is within its signed validity and verifies under a trusted issuer, both signature halves | Who presents it; its status |
+| `StatusEvidence` (`checkStatus`) | The status of that exact document, its source, and its times | Anything about another document of the same DID |
+| `Standing` (`standing`) | Whether that exact document stands now: valid, with fresh evidence of its status | That anyone presents it, or may do anything with it |
+| `AuthenticCredential` (`verifyAuthenticity`) | A retained document verifies under a trusted issuer as `verifyCredential` checks it, except against the current time | That it is valid now, its status, or anything a current result says |
+| `RetainedStatus` (`readRetainedStatus`) | What a retained, signed list said about that document during the list's own validity | Its status now |
+
+None of them is a decision to run anything. Who presents a credential, and what they may
+do, is ARIA AP's: its admission, not a field here, is what lets an operation run.
+
+## Results are the verifier's own: runtime provenance
+
+A result object is a deeply frozen **view**. The verifier that produced it keeps the
+authoritative snapshot in private storage keyed by that object's identity, and every
+consumer (`checkStatus`, `facts`, `standing`, and through them ARIA AP) reads the
+snapshot, never the view's fields. Therefore:
+
+- a spread copy, a copy with every own property and symbol, or a cast object is refused
+  (`AriaUsageError`), whatever it contains;
+- a view cannot be altered in place: it is frozen, times are RFC 3339 strings and the
+  holder key is its multibase string (the 32 bytes stay inside the verifier);
+- a result is accepted only by the verifier instance that produced it. A trust profile's
+  `id` (`demo`, `production`) is a label, not a trust identity: another verifier, even with
+  the same label or keys, refuses it;
+- the trusted configuration is copied and frozen when the verifier is created; later
+  changes to the caller's key bytes or arrays change nothing;
+- time-sensitive evidence is judged when it is used: `standing` judges at each call, so
+  a credential verified earlier can be expired at admission, and status evidence fresh
+  then can be stale now;
+- two installed copies of this package are two separate records: each refuses the
+  other's results, so a duplicated install fails closed, never open.
+
+Install one copy and create the verifier once per trust configuration; ARIA AP takes that
+instance (`createAp({ credentials })`) instead of creating its own.
+
+Types alone are not the boundary (a spread keeps the type); the runtime record is.
+
+## Building on this package: `facts` and `standing`
+
+ARIA AP, or any package built on this one, must reuse this verifier's work without
+trusting a result's fields: a copy, a cast or another verifier's object carries the
+same fields. Two methods are the whole interface:
+
+- **`facts(credential)`** returns what the verifier recorded for one of its own
+  `VerifiedCredential` results: binding, DID, issuer, level, scopes, `hitlRequired`,
+  delegation depth, validity, and the holder key as its 32 raw bytes. Each call returns a
+  fresh copy; changing it changes nothing the verifier holds.
+- **`standing(credential, status)`** judges, at the call and with the verifier's clock,
+  skew and maximum ages, whether that exact credential is inside its signed validity and
+  `status` is this verifier's evidence about that same result, available, fresh and
+  active. In order: `not_valid_now`; `unknown` (`other_document`, `unavailable`,
+  `stale`); `revoked`; `superseded`; `good`. Unknown is never good.
+
+Both throw `AriaUsageError` for anything this verifier did not produce. What they return
+is data and a judgment, not evidence: no entry point of this package or of ARIA AP
+accepts them in place of a result. They exist so that a package built on this one never
+reads a result's fields and never verifies a credential or its status a second time.
+
+A result is evidence only inside the process and the verifier that produced it. Data
+that crosses a process boundary is verified again where it arrives.
+
+## Trust boundary
+
+**Trusted configuration** — supplied by the adopter, never read from a message, copied
+when the verifier is created: trust profiles (issuer DID, the `verificationMethod` its
+proofs name, both public keys, highest level, the status lists it publishes, its online
+status endpoint), the fetch policy (exact allowed origins, time and size bounds, the
+fetch implementation; redirects are never followed), the clock, maximum status ages and
+clock skew. ARIA AP adds its own (receiver identity, operations, stores, approvals).
+
+**Untrusted input** — everything that arrives: credentials, status lists and online
+answers. Nothing in them selects a trust anchor or a fetch target outside the allowed
+origins.
+
+There is no global configuration and nothing embedded: a verifier trusts exactly its
+profiles. The level order is protocol, not configuration: `TRUST_LEVELS` lists the levels
+lowest first and is frozen, so no consumer can reorder the ranking this verifier and
+ARIA AP apply.
+
+## Credential verification (S1)
+
+`verifyCredential(document)` accepts an object or JSON text up to 100 KB, works on a
+private copy, and returns the first failure in this order:
+
+1. not a JSON object (`malformed`), `spec_version` other than `"1.0"` (`unsupported_version`);
+2. the AID 1.0 schema (`malformed`, with a JSON pointer);
+3. an issuer no profile names (`untrusted_issuer`);
+4. proof metadata other than the profile's — `DataIntegrityProof`,
+   `mldsa65-ed25519-2026`, `assertionMethod`, the profile's `verificationMethod`
+   (`unsupported_proof`). These values are checked, not signed: the suite signs the
+   document without its `proof`;
+5. both signature halves over the canonical document (`signature_invalid`);
+6. strict RFC 3339 validity, ordered, current within the skew (`invalid_validity`,
+   `not_yet_valid`, `expired`);
+7. the holder key: exactly 32 raw Ed25519 bytes in ARIA's own encoding (D6), under
+   the subject's DID, and acceptable by the authority's own rule — the canonical
+   encoding of a point, not of small order, torsion free
+   (`holder_key_invalid`). The identity point and other weak keys cannot establish
+   possession, so they are refused here, not only at issuance;
+8. rules the schema cannot express: `hitlRequired` within `scope` (`semantic_invalid`);
+9. a level above the profile's maximum (`level_not_trusted`);
+10. a status list the profile does not publish (`status_list_untrusted`).
+
+The result has no issuance time: `validFrom` and `validUntil` are the signed bounds and
+`proof.created` is unsigned. `previousCredentialId` is returned as data and never fetched:
+it relates a renewal to the credential before it (D11), and the DID does not change.
+
+## Status (S1)
+
+`checkStatus(credential, { via })` concerns the exact document:
+
+- **`status-list`** (default) fetches the list the credential names, from an allowed
+  origin, and reads it only after it verifies under the same profile: issuer, proof
+  profile, both signatures, its signed `id` equal to the list the credential names
+  (another genuine list of the same issuer is refused), the supported subject
+  (`BitstringStatusList`, purpose `revocation`, one bit per entry), and `encodedList` as
+  multibase `u` + base64url GZIP, decompressed within 2 MiB and at least 131,072 entries.
+  Its times are then judged at completion, not when the request started: a validity
+  window of at most 24 hours that holds now, and an age from its own signed `validFrom`
+  within `statusMaxAgeSeconds` (default 3600). `fetchedAt` is that completion time,
+  reported apart from the list's signed times.
+- **`online`** asks the profile's `onlineStatus` endpoint for the DID. Only a complete
+  answer counts — the DID, an exact document reference and a status; anything less is
+  `unavailable`. It has no signed time, is stamped when observed, is only as strong as
+  TLS to that configured endpoint, and `standing` treats it as fresh for
+  `onlineStatusMaxAgeSeconds` (default 60). A complete answer naming another current
+  document makes the presented one `superseded`; a revocation bit never does.
+- Anything not established is `unavailable` with a reason (`offline`, `origin_not_allowed`,
+  `fetch_failed`, `too_large`, `malformed`, `signature_invalid`, `wrong_issuer`,
+  `not_valid_now`, `stale`, `no_online_endpoint`); its standing is `unknown`, which ARIA AP's
+  admission treats as `indeterminate`.
+
+## Historical authenticity
+
+Checking a past statement (an ARIA AP receipt signed by a receiver whose credential has
+since expired) needs the document's authenticity, not its current validity. Three
+methods give that, apart from everything that judges a credential now:
+
+- **`verifyAuthenticity(document)`** runs the checks of `verifyCredential` in the same
+  order except `not_yet_valid` and `expired`: shape, version, schema, issuer, proof
+  profile, both signature halves, a validity interval, holder key, rules, level and
+  trusted status list. Its result is an `AuthenticCredential`, a provenance record of
+  its own kind: `facts`, `standing` and `checkStatus` refuse it, and so does everything
+  in ARIA AP that admits or signs.
+- **`readRetainedStatus(credential, list)`** reads a retained list offline, as
+  `checkStatus` reads a fetched one (issuer, the exact list the credential names, both
+  signatures, the supported subject, at most 24 hours of validity), but never judges its
+  times against now: it reports them. A `RetainedStatus` is not status evidence.
+- **`historicalFacts(credential, status?)`** is the read path, like `facts`: binding,
+  DID, holder key bytes, validity, and what the retained list said. It refuses anything
+  this verifier did not produce and a retained status about another document.
+
+```ts
+const authentic = verifier.verifyAuthenticity(retainedDocument);
+if (authentic.ok) {
+  const read = await verifier.readRetainedStatus(authentic.credential, retainedList);
+  // ARIA AP: ap.verifyHistoricalReceipt(receipt, { attempts, evidence: { credential: authentic.credential, status } })
+}
+```
+
+## `did:aria` identifiers
+
+`parseDid(value)` returns the parts of a `did:aria` identifier, or `null`: one of the
+four shapes of specification §3.1 (`agent-domain-form`, `agent-registry-form`,
+`principal-domain-form`, `principal-registry-form`), with its domain or registry host,
+account and agent name. It applies the same rules as the authority's parser and passes
+the 22 shared cases in `conformance/vectors/abnf-cases.json`. Use it for identifiers being
+created or compared; verifying a credential does not apply it, since a signed 1.0
+document is read under its own schema.
+
+## Credential profile
+
+`spec_version` `"1.0"` (`schema/aid-1.0.json`, embedded byte for byte and checked by a
+test) is the supported profile. Its holder key is 32 raw Ed25519 bytes under
+`Ed25519VerificationKey2020` — ARIA's own encoding (D6), `z` and base58btc of the raw
+key, not the Multikey one; the SDK decodes exactly 32 bytes and projects `0xed01` only
+when producing a Multikey. The proof metadata is outside the signed bytes: the SDK requires the supported
+values, which does not make them signed (D12: the suite is kept for 1.0; the dates that
+count are the signed `validFrom` and `validUntil`, not `proof.created`).
+
+## Package and runtimes
+
+- ESM only, with type declarations; `exports` has the package entry, `package.json`, and
+  `schemas/aid-1.0.json`, a byte-identical copy of the protocol's schema, so that schemas
+  referring to it (ARIA AP's identity response) compile outside this repository.
+  The dependencies are `@noble/curves`, `@noble/hashes`, `@noble/post-quantum`, `ajv` and
+  `ajv-formats`.
+- Node.js 20 and 22: everything (declared; the artifact check in
+  [`../scripts/check-pair.mjs`](../scripts/check-pair.mjs) runs on the Node.js it is given).
+- Browsers and edge runtimes: offline credential checks, with two limits: the schema
+  validator compiles code at run time, which a strict Content Security Policy forbids,
+  and network status checks there cannot enforce private-network restrictions.
+
+The package has no install scripts and reads no environment file.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/MIGRATION.md

@@ -0,0 +1,86 @@
+# From `@aria-registry/verify` 1.x to the ARIA SDK 1.0 and ARIA AP
+
+`@aria-registry/verify` 1.x is replaced by two packages in the same repository:
+
+- **the ARIA SDK** (this package, `@trustlayer-foundation/aria-sdk`) for credentials
+  and their status;
+- **ARIA AP** (`@trustlayer-foundation/aria-ap`, [`../aria-ap-ts`](../aria-ap-ts/README.md))
+  for authenticating requests, admitting them and receipts. It builds on the ARIA SDK's
+  verifier.
+
+A credential-only consumer migrates to the first; a consumer that decides whether an
+agent may do something needs both. `@aria-registry/verify` 1.x is no
+longer served by npm; its source stays in `sdk/verify-ts/` for reference.
+
+## The one change that matters
+
+```ts
+// 1.x
+const result = verifyAgent(credential, { policy });
+if (result.valid) execute();
+```
+
+`valid` could be `true` with the signature check skipped, with the requested policy
+failed, with the status never checked, and with nobody proving the holder key. It was
+never a decision to run anything, and there is no compatibility wrapper that keeps it.
+
+```ts
+// 1.0: authenticate, then admit; only `allow` runs
+const verifier = createVerifier({ trust });           // @trustlayer-foundation/aria-sdk
+const ap = createAp({ credentials: verifier });       // @trustlayer-foundation/aria-ap
+const presented = await ap.verifyPresentation(request, context);
+if (!presented.ok) return presented.status;
+const status = await verifier.checkStatus(presented.presentation.credential);
+const admission = await ap.admit({ presentation: presented.presentation, status, authorize });
+if (admission.decision !== 'allow') return admission.refusal.status;
+await execute();
+```
+
+An operation that must happen once, or that the caller needs a receipt for, runs
+through ARIA AP's `OperationLedger` (see `../aria-ap-ts/examples/protected-handler.ts`).
+
+A consumer that only displays or records whether a credential is genuine and current
+uses `verifyCredential`, `checkStatus` and `standing` (see `examples/verify-credential.ts`),
+and must not treat the answer as permission to act.
+
+## Field by field
+
+| 1.x | 1.0 |
+|---|---|
+| `verifyAgent(c)` | `createVerifier({ trust }).verifyCredential(c)`; status and admission are separate calls |
+| `verifyAgent(c, { skipSignatureCheck: true })` | `inspectCredential(c)`: returns an `Inspection`, never a verified result |
+| `setRegistryKeys(...)`, embedded registry keys | `createVerifier({ trust: [profile] })`: explicit, per verifier, nothing global or embedded |
+| `result.valid` | `CredentialResult.ok` for the document only; `standing(...).state === 'good'` for now; ARIA AP's `Admission.decision === 'allow'` to run |
+| `result.reason` (free text) | fixed reasons: `CredentialFailure`, `StatusUnavailable`, standing states; in ARIA AP, `RequestInvalidReason`, `AuthenticationReason`, `AdmissionReason` |
+| `result.signatures.pqValid/classicalValid` | both required; a failure is `signature_invalid` |
+| `result.expired` | `not_yet_valid`, `expired` or `invalid_validity`, with strict instants |
+| `result.issuedAt` | `validFrom` (signed, RFC 3339 string). There is no issuance time: `proof.created` is not signed |
+| `result.expiresAt` | `validUntil` |
+| `result.credentialId`, `previousCredentialId` | `credential.binding.credentialId`; `credential.previousCredentialId` as data, never fetched |
+| `result.revocationStatus`, `revocationCheckedAt` | `checkStatus(credential)` → `StatusEvidence` with source, signed list times and `fetchedAt` |
+| `checkRevocation(did)` | removed: it asked about a DID, not the presented document |
+| `checkCredentialStatus(c, { via })` | `checkStatus(credential, { via: 'status-list' \| 'online' })`; the online endpoint is the profile's `onlineStatus` |
+| `policy.requiredScopes`, `minTrustLevel` | ARIA AP: `OperationDescriptor.scope`, `minLevel`, enforced by `admit` |
+| `policy.requireRevocationCheck`, `lastRevocationCheck`, `maxOfflineAge` | `statusMaxAgeSeconds`, from the signed list's `validFrom`, judged by `standing` at use; a fresh fetch time is not evidence |
+| `result.hitlRequired` | `credential.hitlRequired`, a declaration; the approval is ARIA AP's `ApprovalEvidence` at `admit` |
+| `PolicyLevel` presets | none: each operation states its level and scope |
+| `canonicalJson` | `canonicalJson`, the ARIA canonical form (INVARIANTS §3) |
+| results as plain objects you could copy or edit | frozen views the producing verifier recognises by identity; copies and other verifiers' results throw `AriaUsageError` |
+
+## What the old characterizations become
+
+The 1.x probes recorded behaviors; they are not all defects. In the 1.0 tests:
+
+- **kept as controls**: a valid baseline passes schema and both signatures; altered signed
+  content and an expired credential are refused;
+- **turned into rejections**: not-yet-valid, invalid or inverted validity bounds, a
+  missing holder key, the skipped signature check (now inspection only), a failed
+  requested scope (now an ARIA AP `deny`), a revoked status discarded by the old recipe
+  (now `revoked` standing and an ARIA AP `deny`), unsupported proof metadata (refused,
+  still unsigned);
+- **checked at their own layer**: a copied credential still verifies as a document but
+  cannot be admitted without its holder key; offline verification succeeds with unknown
+  status and an `unknown` standing, while an ARIA AP admission that needs status is
+  `indeterminate`;
+- **schema versus rules**: the schema alone accepts `hitlRequired` outside `scope`; the
+  SDK refuses it as `semantic_invalid`.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# ARIA SDK (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The ARIA SDK for ARIA 1.0: inspect and verify an agent's credential, and establish the
+status of that exact document.
+
+**Version 1.0.0.** This directory holds the API contract and its implementation:
+inspection, per-verifier trust, credential verification, exact-instance status, and the
+trust interface packages built on it use. It trusts no issuer by default: each verifier
+states the issuers it accepts.
+
+**Which package.** This repository has two SDK packages. A service that only checks
+credentials installs this one. A service that authenticates agent requests, admits them
+or exchanges receipts also installs [ARIA AP](../aria-ap-ts/README.md), which builds on
+this package's verifier and has none of its own. `@aria-registry/verify` 1.x is no
+longer served by npm; see the migration guide.
+
+- [API contract](API.md): the results, runtime provenance, `facts` and `standing`, the
+  trust boundary, credential and status verification, historical authenticity, the
+  credential profile, runtimes.
+- [Migration from `@aria-registry/verify` 1.x](MIGRATION.md).
+- `examples/verify-credential.ts`: checking a credential and its standing, which is not
+  admitting a request.
+- `test-d/`: the boundaries the types enforce.
+
+`pnpm typecheck` compiles the sources, examples, tests and boundary checks; `pnpm test`
+runs the tests, with synthetic issuer keys made per run; `pnpm build` writes `dist/`.
+`node ../scripts/check-pair.mjs` packs this package and ARIA AP and checks both as
+installed artifacts, alone and together.