[RFC] Authentication and Authorization

[andrewmd5]

Within this post you'll find an overview of the abstraction Tempo provides to handle authentication (verifying the identity of a peer or service) and authorization (determines their access rights.)

Setting Credentials

If your API requires user authentication, it is crucial to provide a way to assign user credentials for subsequent requests to a Tempo server. The ServerContext instance, passed into each service method implementation, exposes a method called setOutgoingCredentials.

Credentials are defined as:

type CredentialPrimitiveValue = string | number | boolean | bigint;
type NestedCredentialObject = {
    [K in string]: CredentialValue;
};
type CredentialValue = CredentialPrimitiveValue | Map<string, CredentialPrimitiveValue> | Array<CredentialPrimitiveValue> | NestedCredentialObject;
/**
 * A type representing credentials as a record of key-value pairs.
 */
type Credentials = Record<string, CredentialValue>;

For example, if you're using JWT for authorization in your API, you could sign the token and supply it to setOutgoingCredentials as follows:

context.setOutgoingCredentials({token: "signature"});

When the response is sent to a client, the Credentials are serialized and set on the tempo-credentials header. The client stores the credentials if configured to do so.

It's also possible to extend the interface, allowing you to build additional functionality based on the concept of Credentials:

/**
 * A utility type that gets the known keys of a given type `T` by excluding index signatures.
 */
type KnownKeys<T> = keyof ExcludeIndexSignature<T>;
type CredentialAlgorithm = 'HS256' | 'RS256';
type CredentialType = 'TWT';
/**
 * Interface representing a session credential with a token and claims.
 * Extends the generic `Credentials` type.
 */
interface ISessionCredential extends Credentials {
    header: {
        algo: CredentialAlgorithm;
        typ: CredentialType;
    };
    claims: {
        nonce: string;
        exp: number;
        tid: string;
        user: {
            id: string;
            username: string;
            flags: number;
            discriminator: number;
        };
    };
}
/**
 * A type alias for the known keys of `ISessionCredential`.
 */
type KnownKeysOfISessionCredential = KnownKeys<ISessionCredential>;
/**
 * A mapped type that maps over `KnownKeysOfISessionCredential` and extracts the properties from `ISessionCredential`.
 */
type SessionCredentialMapped = {
    [K in KnownKeysOfISessionCredential]: ISessionCredential[K];
};
/**
 * A class implementing `SessionCredentialMapped` that provides proxy-based access to its properties.
 * Ensures type safety for property access when using index signatures.
 */
declare class SessionCredential implements SessionCredentialMapped {
    constructor(credentials: ISessionCredential);
    static fromToken(credentials: Credentials | undefined): SessionCredential;
    isExpired(): boolean;
    sign(secret: string, signer: (secret: Uint8Array, data: Uint8Array) => Promise<Uint8Array>): Promise<Credentials>;
    static verify(credential: Credentials | undefined, secret: string, verifier: (secret: Uint8Array, data: Uint8Array, signature: Uint8Array) => Promise<boolean>): Promise<boolean>;
    /**
     * Returns the current instance as a `Credentials` type.
     * This is safe because we provide a proxy for index signature access.
     */
    asCredentials(): Credentials;
    header: {
        algo: CredentialAlgorithm;
        typ: CredentialType;
    };
    claims: {
        nonce: string;
        exp: number;
        tid: string;
        user: {
            id: string;
            username: string;
            flags: number;
            discriminator: number;
        };
    };
}

Intercepting Credentials

The @tempojs/server package also exposes an AuthInterceptor abstract class, which can be implemented and passed into the constructor of a router. The purpose of AuthInterceptor is to allow your code to inspect a request with its Authorization header set so you can perform validation and populate an AuthContext that will be forwarded to service methods. Below is an example implementation of AuthInterceptor that verifies a JWT and authenticates a peer:

/**
 * TokenInterceptor is an extension of the AuthInterceptor class, which checks
 * the validity of the session token in the authorization header and sets
 * authentication context properties based on the decoded session token.
 */
export class TokenInterceptor extends AuthInterceptor {
	/**
	 * Constructs a new TokenInterceptor instance.
	 * @param logger - The logger to use for debug logging.
	 */
	constructor(private logger: TempoLogger) {
		super();
	}

	/**
	 * Intercepts the request, verifies the session token, and sets the
	 * authentication context properties based on the decoded session token.
	 * @param context - The server context of the request.
	 * @param authorizationValue - The authorization header value.
	 * @returns A promise that resolves with the authentication context.
	 */
	async intercept(context: ServerContext, authorizationValue: string): Promise<AuthContext> {
		const authContext = new AuthContext();
		const bearerScheme = 'Bearer';
		const headerParts = authorizationValue.trim().split(' ');

		// Check if the authorization header format is invalid
		if (headerParts.length !== 2 || headerParts[0] !== bearerScheme) {
			this.logger.debug('Invalid authorization header format', { headerParts });
			// Invalid authorization header format
			return Promise.resolve(authContext);
		}

		const credential: Credentials = { token: headerParts[1] };

		// Verify the session token
		const isValid = await SessionCredential.verify(
			credential,
			context.getEnvironment<Env>().SESSION_TOKEN_SECRET,
			async (secret, data, signature) => {
				const cryptoKey = await crypto.subtle.importKey(
					'raw',
					secret,
					{
						name: 'HMAC',
						hash: 'SHA-256',
					},
					false,
					['verify'],
				);

				return crypto.subtle.verify('HMAC', cryptoKey, signature, data);
			},
		);

		// If the session token is valid, set the authentication context properties
		if (isValid) {
                         // DON'T LOG IN PRODUCTION
			this.logger.debug('Valid session token', { credential });
			const sessionToken = SessionCredential.fromToken(credential);

			if (!sessionToken.isExpired()) {
				authContext.addProperty('user', sessionToken.claims.user.username);
				authContext.addProperty('user', sessionToken.claims.user.id);
				authContext.addProperty('user', sessionToken.claims.user.flags);
				authContext.addProperty('user', sessionToken.claims.user.discriminator);
				authContext.setPeerIdentityPropertyName('user');
				this.logger.debug('set auth context', { identity: authContext.peerIdentity });
			}
		}

		return authContext;
	}
}

To clarify a few points:

• In a Tempo-based system, a peer can be a client, a server, or both, depending on the context and the communication pattern. When a Tempo client initiates a call, it contacts a server or another peer that offers the desired service. A service could talk to another service on behalf of the client while impersonating the client by setting its credentials.
• An AuthContext is a collection of properties relevant to the context of a request. Importantly, when you set setPeerIdentityPropertyName, you're indicating that the peer, and by extension the AuthContext, is authenticated.

In the example above, we're not throwing an error - this is because an empty AuthContext will always be unauthenticated, so it is still safe to pass to a method that requires authentication, provided you check that the AuthContext is authenticated. You can throw a TempoError(TempoStatusCode.Unauthenticated) in intercept if you want (and it will propagate back to the client), however, we recommend throwing in the method that requires an authenticated context instead, so you don't become reliant on a middleware pattern.

async protectedMethod(record: ISomeData, context: ServerContext): Promise<ISomeResponse> {
	const authContext = context.getAuthContext();
	if (!authContext?.isPeerAuthenticated) {
		throw new TempoError(TempoStatusCode.UNAUTHENTICATED, 'UNAUTHENTICATED');
	}
	authContext.peerIdentity?.forEach((prop) => {
		this.logger.debug(`${prop.name} / ${prop.value}`);
	});
}

Storing Credentials

At this time, Tempo does not support setting cookies (or any custom response headers), nor does it expose a way of accessing them through the abstraction short of manually parsing incoming headers. As such, the @tempojs/client package exposes an abstraction to allow clients to store credentials received via the tempo-credentials header so they can automatically be put on request:

/**
 * An interface defining the methods required for a credentials storage strategy.
 */
interface CredentialsStorage {
    /**
     * Retrieves stored credentials for a given key.
     * @param key - The key associated with the stored credentials.
     * @returns A Promise that resolves with the credentials, or undefined if not found.
     */
    getCredentials(key: string): Promise<Credentials | undefined>;
    /**
     * Stores credentials for a given key.
     * @param key - The key associated with the credentials to store.
     * @param credentials - The credentials to store.
     * @returns A Promise that resolves when the credentials have been stored.
     */
    storeCredentials(key: string, credentials: Credentials): Promise<void>;
    /**
     * Removes the credentials stored for a given key.
     * @param key - The key associated with the credentials to store.
     */
    removeCredentials(key: string): Promise<void>;
}
/**
 * An implementation of CredentialsStorage using the browser's localStorage.
 */
declare class LocalStorageStrategy implements CredentialsStorage {
    getCredentials(key: string): Promise<Credentials | undefined>;
    storeCredentials(key: string, credentials: Credentials): Promise<void>;
    removeCredentials(key: string): Promise<void>;
}
/**
 * An implementation of CredentialsStorage using the browser's sessionStorage.
 */
declare class SessionStorageStrategy implements CredentialsStorage {
    getCredentials(key: string): Promise<Credentials | undefined>;
    storeCredentials(key: string, credentials: Credentials): Promise<void>;
    removeCredentials(key: string): Promise<void>;
}
/**
 * A no-operation implementation of CredentialsStorage that does not store or retrieve credentials.
 */
declare class NoStorageStrategy implements CredentialsStorage {
    getCredentials(_key: string): Promise<Credentials | undefined>;
    storeCredentials(_key: string, _credentials: Credentials): Promise<void>;
    removeCredentials(_key: string): Promise<void>;
}

These strategies are used on implementations of CallCredentials:

/**
 * An abstract class representing the base for all CallCredentials implementations.
 */
declare abstract class CallCredentials {
    protected storage: CredentialsStorage;
    protected key: string;
    protected constructor(storage: CredentialsStorage, key: string);
    /**
     * Retrieves stored credentials.
     * @returns A Promise that resolves with the credentials, or undefined if not found.
     */
    abstract getCredentials(): Promise<Credentials | undefined>;
    /**
     * Retrieves the HTTP header to be used for authentication.
     * @returns A Promise that resolves with the header, or undefined if not applicable.
     */
    abstract getHeader(): Promise<Header | undefined>;
    /**
     * Stores credentials.
     * @param credentials - The credentials to store.
     * @returns A Promise that resolves when the credentials have been stored.
     */
    abstract storeCredentials(credentials: Credentials): Promise<void>;
    /**
     * Remove credentials.
     * @param credentials - The credentials to remove.
     * @returns A Promise that resolves when the credentials have been removed.
     */
    removeCredentials(): Promise<void>;
}
/**
 * An implementation of CallCredentials for insecure (unauthenticated) channels.
 */
declare class InsecureChannelCredentials extends CallCredentials {
    /**
     * Retrieves stored credentials. Always returns undefined for insecure channels.
     * @returns A Promise that resolves with undefined.
     */
    getCredentials(): Promise<Credentials | undefined>;
    /**
     * Retrieves the HTTP header for authentication. Always returns undefined for insecure channels.
     * @returns A Promise that resolves with undefined.
     */
    getHeader(): Promise<Header | undefined>;
    /**
     * Stores credentials. Does nothing for insecure channels.
     * @param credentials - The credentials to store.
     * @returns A Promise that resolves immediately.
     */
    storeCredentials(_credentials: Credentials): Promise<void>;
    /**
     * Creates a new instance of InsecureChannelCredentials.
     * @returns A new instance of InsecureChannelCredentials.
     */
    static create(): InsecureChannelCredentials;
}
/**
 * An implementation of CallCredentials for Bearer token authentication.
 */
declare class BearerCredentials extends CallCredentials {
    constructor(storage: CredentialsStorage, key: string);
    /**
     * Retrieves stored credentials from the storage strategy.
     * @returns A Promise that resolves with the credentials, or undefined if not found.
     */
    getCredentials(): Promise<Credentials | undefined>;
    /**
     * Retrieves the HTTP header for Bearer token authentication.
     * @returns A Promise that resolves with the header, or undefined if the token is not available.
     */
    getHeader(): Promise<Header | undefined>;
    /**
     * Stores credentials using the storage strategy.
     * @param credentials - The credentials to store.
     * @returns A Promise that resolves when the credentials have been stored.
     */
    storeCredentials(credentials: Credentials): Promise<void>;
    /**
     * Creates a new instance of BearerCredentials with the specified storage strategy and key.
     * @param storage - The storage strategy to use for storing and retrieving credentials.
     * @param key - The key associated with the credentials.
     * @returns A new instance of BearerCredentials.
     */
    static create(storage: CredentialsStorage, key: string): BearerCredentials;
}

You can, of course, implement a custom CallCredentials to fit your use-case:

declare class SessionCallCredentials extends CallCredentials {
    constructor(storage: CredentialsStorage, key: string);
    /**
     * Retrieves stored credentials from the storage strategy.
     * @returns A Promise that resolves with the credentials, or undefined if not found.
     */
    getCredentials(): Promise<Credentials | undefined>;
    /**
     * Retrieves the HTTP header for Bearer token authentication.
     * @returns A Promise that resolves with the header, or undefined if the token is not available.
     */
    getHeader(): Promise<any | undefined>;
    /**
     * Stores credentials using the storage strategy.
     * @param credentials - The credentials to store.
     * @returns A Promise that resolves when the credentials have been stored.
     */
    storeCredentials(credentials: Credentials): Promise<void>;
    getSessionCredential(): Promise<SessionCredential>;
}

Then, when creating a channel, you supply the CallCredentials implementation:

const credentials = new SessionCallCredentials(new LocalStorageStrategy(), 'session');
const target = 'http://localhost:8787';
console.log('target', target);
const channel = TempoChannel.forAddress(target, {
	credentials: credentials,
        // necessary when transmitting credentials to an insecure target (non-https)
       // only use this for development 
	unsafeUseInsecureChannelCallCredentials: true
});
const client = channel.getClient(UserClient);

When you make a call to a remote method that sets credentials, the client will now store them automatically:

const signInResult = await client.signIn({
	email: 'example@acme.com',
	password: '123456780',
});
//SessionCredential is a custom implementation of Credentials
const sessionCred = SessionCredential.fromToken(await client.getCredentials());
console.log( JSON.stringify(sessionCred.claims));

Questions for You

1. Does the proposed abstraction offer a straightforward and consistent interface for handling authentication and authorization across various authentication providers and methods?
2. Are there any drawbacks, limitations, or potential security risks associated with the proposed abstraction? Are there any performance concerns?
3. Can the abstraction be easily integrated with existing and future authentication providers and systems, such as OAuth, SAML, JWT, LDAP, or custom solutions?
4. Is the abstraction versatile enough to accommodate different authorization models, including role-based access control (RBAC), attribute-based access control (ABAC), or others?
5. How does the proposed abstraction handle error scenarios and edge cases, like expired tokens, revoked access, or insufficient permissions?
6. How does the abstraction support testing and debugging of authentication and authorization-related code? Should any built-in types or utilities be included for this purpose?
7. Are there any best practices or design patterns the abstraction should adhere to in order to ensure extensibility, maintainability, and security?
8. What are some real-world use cases or scenarios where the proposed abstraction would be particularly useful or problematic?
9. Should any alternatives or competing solutions be considered, and why might they be more or less suitable than the proposed abstraction?
10. How well does the abstraction align with Tempo's overall goals, philosophy, and design principles? Is it easy for developers to adopt and comprehend?
11. Are the names of certain types (e.g., AuthContext, CallCredentials vs. Credentials, etc.) clear and easy to understand for users, or might there be confusion regarding their usage and purpose?