// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package permissions defines an interface for managing access control
// permissions.
package permissions

import (
	"v.io/v23/security/access"
)

// Object provides access control for Vanadium objects.
//
// Vanadium services implementing dynamic access control would typically embed
// this interface and tag additional methods defined by the service with one of
// Admin, Read, Write, Resolve etc. For example, the VDL definition of the
// object would be:
//
//   package mypackage
//
//   import "v.io/v23/security/access"
//   import "v.io/v23/services/permissions"
//
//   type MyObject interface {
//     permissions.Object
//     MyRead() (string, error) {access.Read}
//     MyWrite(string) error    {access.Write}
//   }
//
// If the set of pre-defined tags is insufficient, services may define their
// own tag type and annotate all methods with this new type.
//
// Instead of embedding this Object interface, define SetPermissions and
// GetPermissions in their own interface. Authorization policies will typically
// respect annotations of a single type. For example, the VDL definition of an
// object would be:
//
//  package mypackage
//
//  import "v.io/v23/security/access"
//
//  type MyTag string
//
//  const (
//    Blue = MyTag("Blue")
//    Red  = MyTag("Red")
//  )
//
//  type MyObject interface {
//    MyMethod() (string, error) {Blue}
//
//    // Allow clients to change access via the access.Object interface:
//    SetPermissions(perms access.Permissions, version string) error         {Red}
//    GetPermissions() (perms access.Permissions, version string, err error) {Blue}
//  }
type Object interface {
  // SetPermissions replaces the current Permissions for an object.  version
  // allows for optional, optimistic concurrency control.  If non-empty,
  // version's value must come from GetPermissions.  If any client has
  // successfully called SetPermissions in the meantime, the version will be
  // stale and SetPermissions will fail.  If empty, SetPermissions performs an
  // unconditional update.
  //
  // Permissions objects are expected to be small.  It is up to the
  // implementation to define the exact limit, though it should probably be
  // around 100KB.  Large lists of principals can be represented concisely using
  // blessings.
  //
  // There is some ambiguity when calling SetPermissions on a mount point.
  // Does it affect the mount itself or does it affect the service endpoint
  // that the mount points to?  The chosen behavior is that it affects the
  // service endpoint.  To modify the mount point's Permissions, use
  // ResolveToMountTable to get an endpoint and call SetPermissions on that.
  // This means that clients must know when a name refers to a mount point to
  // change its Permissions.
  SetPermissions(perms access.Permissions, version string) error {access.Admin}

  // GetPermissions returns the complete, current Permissions for an object. The
  // returned version can be passed to a subsequent call to SetPermissions for
  // optimistic concurrency control. A successful call to SetPermissions will
  // invalidate version, and the client must call GetPermissions again to get
  // the current version.
  GetPermissions() (perms access.Permissions, version string | error) {access.Admin}
}