Skip to main content

Get started with the NodeJS SDK for Government

First, start by importing the Archon object and configuring your NodeJS component's name

import { Archon } from '@archon-inc/sdk'

Archon.setComponentName('my-app')

For more in-depth information, see the TypeDoc at https://archon.inc/sdk/

How does the SDK for Government work?​

Archon SDK for Government provides compliant mechanisms for several common use cases. To achieve compliance, you will need to integrate each one into your application. Here are brief overviews of what you need to do for each mechanism.

Authentication​

All traffic in an Archon Environment (See key terms) is guaranteed to be authenticated before reaching your application. Once traffic reaches your app, requests will have an x-session-id header that uniquely identifies the session of the signed in user. A session consists of:

  • A user: The person (or application) performing actions against your application
  • A role: The set of actions this person can take

You'll need to determine the active session for access control, logging, and other activities.

For more info, read 5. Authentication

Access Control​

You need to inform Archon whenever you create a new resource so the Engine (See key terms) can determine which accesses are valid and which are not.

note

A resource is anything a user can access via a role. Think of chats in a chat application, documents in a document manager, or similar. Typically, you should consider assigning a resource any time you create a database entry.

When creating new resources in your application, you should make sure to store the Archon Resource Identifier (abbreviated ARID, more info here) alongside it so you can determine access controls later.

Access is determined by the user and what role they're acting as. This pattern encourages separation of duties, a federal software requirement. Users access resources via intents, like read-document for a document or send-chat for a chat app.

For more info, read 6. Access Control

Configuration Management​

You need to use Archon to store any configuration values or "static authenticators" (think API keys or other secrets) in your application.

note

You should use Config any time you would otherwise pass data in as an environment variable

Archon's Config features implement change control logic when running in production, as well as encrypting secrets at rest and in transit. These are both federal requirements.

For more info, read 7. Config

Logging​

You need to use Archon any time you would log information to the console. You also need to integrate logging into any significant functions of your application if you haven't already.

For more info, read 8. Logging

note

For a better developer experience, you should also check out the Admin Panel for Development. See Get started with Admin Panel for Development

Some common use cases​

Checking a user's session​

All users accessing your application will be authenticated before reaching your component. You can see their authentication information by calling one of these methods

// for users of Express or similar
const session = await getSessionFromReq(requestObject)
// for other use-cases
const session = await getSession("Session ID here")
const session = await getSession(req.headers["x-session-id"])

Adding a new resource​

const documentType = await getResourceType('document')

await addResource({
	type: documentType,
	metadata: {
		// Your metadata here. Must be JSON serializable
	}
})

Checking a user's access to a resource​

const documentType = await getResourceType('document')
const readDocument = getIntent(documentType, 'read-document')

// In a request handler...
const session = await getSessionFromReq(req)

const canAccess = await determineAccess(session, resource.arid, readDocument)

Getting a config value​

// for normal config entries, will return some JSON value depending on what you've entered
const configValue = await getConfigValue('my-value')

// for secret entries
const secretValue = await getSecret('my-secret-value')
note

Your application must have permission to view secrets or config entries! See 7. Config

Logging something​

// log a defined event that occurs many times. Will make log management easier later. Prefer this method where applicable
const PAGE_VIEW = createEventType("page-view")
logEvent(PAGE_VIEW, {
	outcome: Outcome.SUCCESS,
	context: "A user just viewed '/'"
})

// log an error specifically. handles protecting the stack trace from prying eyes, which is a federal requirement
logError(error, {
  context: "Any additional info you may want to add"
})

// drop-in replacement for console.log()
log("Your message")

Signing a user out​

// you can either redirect them to /.archon/authenticate/logout
res.redirect("/.archon/authenticate/logout")

// or your can end their session and give a custom redirect
const session = await getSessionFromReq(req)
await endSession(session)
res.redirect("https://example.com")
note

Once a user is signed out, they will not be able to access your application until reauthenticating

More information​

See more details on every API using the TypeDoc: https://archon.inc/sdk/