@cardanotech/interfaces provides provider-neutral data transfer objects and TypedRequest contracts for cardano.tech products. Version 1 defines the hosted Wallet Proof challenge, completion, receipt, permission, and failure surface.

The package contains contracts only. It does not authenticate callers, persist state, access a Cardano provider, verify signatures, or hold wallet keys.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @cardanotech/interfaces

Exports

The root export contains two namespaces:

data: provider-neutral Wallet Proof DTOs, gateway permissions, and errors;
request: TypedRequest interfaces and their stable method constants.

import { data, request } from '@cardanotech/interfaces';

const startRequest: request.IReq_CreateWalletProofChallenge['request'] = {
  subjectRef: 'subject-internal-0001',
  origin: 'https://app.example',
  network: 'testnet',
  purpose: 'link-wallet',
  idempotencyKey: 'wallet-link-attempt-0001',
};

const method: request.IReq_CreateWalletProofChallenge['method'] =
  request.createWalletProofChallengeMethod;

const permission: data.TCardanoGatewayPermission = 'walletproof.create';

Wallet Proof methods

Method constant	TypedRequest interface	Required permission
`createWalletProofChallengeMethod`	`IReq_CreateWalletProofChallenge`	`walletproof.create`
`completeWalletProofChallengeMethod`	`IReq_CompleteWalletProofChallenge`	`walletproof.complete`
`getWalletProofReceiptMethod`	`IReq_GetWalletProofReceipt`	`walletproof.read`

Create accepts an opaque consumer-local subjectRef, requested origin, network, purpose, and an idempotency key. Complete accepts the browser wallet submission and its own idempotency key. Read accepts a receipt identifier. Successful completion and read responses contain the privacy-safe IWalletProofReceipt.

Authentication and tenant scope

Authentication is intentionally absent from request DTOs. A gateway handler must derive the authenticated workload, tenant, issuer, audience, and permissions from a trusted server-side transport context before it processes any method.

subjectRef is an opaque consumer-backend reference scoped beneath that authenticated context; it is not browser authority and must not contain an email address or other user-facing identifier. Origin, network, and purpose are policy requests that the gateway must allow or reject. Challenge IDs, receipt IDs, and idempotency keys are always looked up inside the authenticated tenant scope and never grant access by themselves.

This package does not choose a credential format for workload authentication. The gateway must not treat a browser user JWT, request-supplied tenant identifier, role, plan, quota, or entitlement as service authority.

Failure contract

Every request interface exposes an optional ICardanoGatewayTypedError. Its text is safe for a caller, while data.code is stable and machine-readable. Error data also carries a request ID, a retryable flag, and an optional retry delay.

Codes distinguish invalid requests, authentication or permission failures, policy denials, absent resources, expired or replayed challenges, failed verification, idempotency conflicts, rate limiting, temporary unavailability, and internal failures. Cross-tenant lookups should use the same safe not_found behavior as an absent identifier.

Wallet Proof compatibility

The Wallet Proof v1 DTOs are structurally compatible with the stable public v1 contracts in @cardanotech/walletproof. They are repeated here so hosted contracts remain provider-neutral and do not require consumers to import protocol implementation code. Future alignment must preserve these published wire shapes.

The default receipt deliberately excludes the raw reward address, COSE signature, COSE key, and signed challenge message. A permissioned raw-evidence response, if ever needed, requires a separate contract and retention decision.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@cardanotech/interfaces