Linked Providers

@absolutejs/linked-providersv0.0.5alphaAuth & Identity

Neutral credential and resolver contracts shared between @absolutejs/auth and the packages that consume linked-provider tokens.

Shared type contracts for linked third-party provider credentials — grants, bindings, resolved credentials, token leases, and the resolver and store interfaces that move them around. It deliberately ships no runtime: @absolutejs/auth implements these contracts, @absolutejs/absolute consumes them, and this package stays the neutral source of truth between them. Depend on it whenever a package needs to talk about linked-provider credentials without pulling in the auth runtime.

#Installation

BASH

bun add @absolutejs/linked-providers

#Capabilities

Overview

Shared linked-provider credential and resolver contracts for AbsoluteJS packages.

This package is intentionally narrow. It provides:

linked provider grant and binding types

Show 3 more

resolved credential and token lease types

generic linked-provider resolver contracts

durable store contracts for grants and bindings

Resolver contract

LinkedProviderCredentialResolver defines listBindings, resolveCredential, getAccessToken, and reportFailure — the full lifecycle a consumer needs from any credential backend.

Grant and binding types

LinkedProviderGrant models an OAuth grant (scopes, encrypted tokens, refresh state); LinkedProviderBinding models a concrete external account riding that grant.

Token lease shape

LinkedProviderAccessTokenLease carries an access token with expiry and granted scopes, so consumers can request minimum validity windows without seeing refresh mechanics.

Durable store contracts

LinkedProviderGrantStore and LinkedProviderBindingStore define the persistence surface, letting any database back the auth implementation.

Open provider unions

Provider unions (google, linkedin, x, meta, gmail, instagram, facebook) stay open via string augmentation, so new providers slot in without a breaking change.

Outcomes

What you can build

Overview

Shared linked-provider credential and resolver contracts for AbsoluteJS packages.

Resolver contract

It does not provide:

Hardening checklist

Production guidance

Make every external boundary explicitPin the deployed @absolutejs/linked-providers version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.

Follow in order

Troubleshooting path

Trace from the first failed boundary

Reproduce the smallest canonical @absolutejs/linked-providers example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#Resolver contract

Partial snippet

Working example for Resolver contract.

import type {
	LinkedProviderCredentialResolver,
	ResolveLinkedProviderCredentialInput
} from '@absolutejs/linked-providers';

export const resolveConnectorCredential = (
	resolver: LinkedProviderCredentialResolver,
	input: ResolveLinkedProviderCredentialInput
) => resolver.resolveCredential(input);

#Quick Start

Partial snippet

Consumers program against LinkedProviderCredentialResolver: resolve a credential for a purpose, lease an access token with a minimum validity window, and report failures back so the implementation can mark grants for refresh.

import type {
	LinkedProviderCredentialResolver
} from '@absolutejs/linked-providers';

// A consumer (connector, sync job, RAG source) only needs the
// resolver contract — the implementation lives in @absolutejs/auth.
const syncMailbox = async (
	resolver: LinkedProviderCredentialResolver,
	ownerRef: string
) => {
	const credential = await resolver.resolveCredential({
		connectorProvider: 'gmail',
		ownerRef,
		purpose: 'background_sync',
		requiredScopes: [
			'https://www.googleapis.com/auth/gmail.readonly'
		]
	});
	if (credential === null) return;

	const lease = await resolver.getAccessToken(credential, {
		minValidityMs: 60_000
	});

	// Call the provider API with lease.accessToken; on failure:
	await resolver.reportFailure(credential, {
		code: 'rate_limited',
		retryAt: Date.now() + 30_000
	});
};

Contracts, not runtime

This package contains only types and contracts — no OAuth routes, token refresh, or provider SDK clients. Those live in @absolutejs/auth, which implements these contracts.

Alpha contracts

@absolutejs/linked-providers is 0.0.x — contract shapes may still evolve alongside the auth implementation before 0.1.

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

16 symbols

LinkedProviderFamilytypePermalink

type LinkedProviderFamily = "google" | "linkedin" | "x" | "meta" | (string & {});

Exported from @absolutejs/linked-providers

npm GitHub

Current package surface

What ships today

@absolutejs/linked-providersv0.0.5 · betaAuth & Identitynpm Source

1entry points16symbols

Import surface · click to copy

PreviousCitra NextCompliance